remix 3.0.0-beta.5 → 3.0.0-beta.9

package/src/ui/README.md

@@ -4,7 +4,7 @@ Runtime UI primitives for Remix apps, including the component runtime, server re
 
 ## Features
 
-- Component runtime APIs for rendering, hydration, frame navigation, and JSX
+- Component runtime APIs for rendering, hydration, link and form frame navigation, and JSX
 - Server rendering APIs for streaming Remix UI trees and frames
 - `mix` composition with event, ref, CSS, and animation helpers
 - Headless behavior primitives for controls such as menus, listboxes, popovers, selects, and comboboxes
@@ -79,6 +79,117 @@ function Actions() {
 }
 ```
 
+## Frame Navigation
+
+`run()` progressively enhances same-origin links and forms using a default `resolveFrame` that
+fetches the frame source:
+
+```tsx
+import { run } from 'remix/ui'
+
+let app = run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+})
+
+await app.ready()
+```
+
+The default resolver is equivalent to:
+
+```js
+async function resolveFrame(src, options) {
+  let response = await fetch(src, {
+    body: getRequestBody(options),
+    headers: { Accept: 'text/html' },
+    method: options?.method,
+    signal: options?.signal,
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to resolve frame: ${response.status} ${response.statusText}`.trimEnd())
+  }
+
+  return response
+}
+
+function getRequestBody(options) {
+  let formData = options?.formData
+  if (!formData || options?.method?.toLowerCase() === 'get') return
+
+  if (options?.encType === 'text/plain') {
+    let body = ''
+    for (let [name, value] of formData) {
+      name = normalizeLineBreaks(name)
+      value = normalizeLineBreaks(typeof value === 'string' ? value : value.name)
+      body += `${name}=${value}\r\n`
+    }
+    return new Blob([body], { type: 'text/plain' })
+  }
+
+  if (options?.encType !== 'application/x-www-form-urlencoded') return formData
+
+  let body = new URLSearchParams()
+  for (let [name, value] of formData) {
+    body.append(name, typeof value === 'string' ? value : value.name)
+  }
+  return body
+}
+
+function normalizeLineBreaks(value) {
+  return value.replace(/\r\n|\r|\n/g, '\r\n')
+}
+```
+
+The default resolver requests HTML. GET form values are already encoded in `src`;
+`application/x-www-form-urlencoded` submissions use `URLSearchParams`, `text/plain` submissions use
+CRLF-delimited text, and `multipart/form-data` submissions use `FormData`. Pass a custom
+`resolveFrame` when the server requires additional headers, another body encoding, or a different
+response policy.
+
+Add `rmx-document` to a link or form to leave its navigation to the browser.
+
+The default resolver rejects non-OK responses with an error containing their status and status text.
+A custom `resolveFrame` may return a `Response` with any status when it wants Remix UI to render the
+response body.
+
+Forms remain ordinary HTML forms before the runtime starts. Add `rmx-target` to reload a named frame, or `rmx-document` to require a full-document submission:
+
+```tsx
+import { Frame } from 'remix/ui'
+
+function AccountPage() {
+  return () => (
+    <>
+      <Frame name="account" src="/account/edit" />
+      <form action="/account/edit" method="post" rmx-target="account">
+        <label for="display-name">Display name</label>
+        <input id="display-name" name="displayName" required />
+        <button type="submit">Save</button>
+      </form>
+    </>
+  )
+}
+```
+
+Native constraint validation and submitter overrides still apply. GET form values arrive in `src`; non-GET forms provide `formData`, `method`, and `encType` to the resolver. See [Frames](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md#form-navigation) for targeting, history behavior, request encoding, opt-outs, and server response guidance.
+
+Use `rmx-history="push|replace"` on an enhanced anchor or form to control how the navigation updates history. This can override the automatic replacement used for non-GET form submissions to the current URL.
+
+## Preserving Client-Owned DOM
+
+Use `rmx-preserve-dom` on the smallest element whose live DOM should belong to client code after initial render, such as a custom element or third-party widget:
+
+```tsx
+<pagefind-ui data-key="search" rmx-preserve-dom>
+  <button type="button">Search</button>
+</pagefind-ui>
+```
+
+Remix UI still renders the element's children during SSR and still hydrates any initial client entries inside it. On later frame reloads, matched `rmx-preserve-dom` elements keep their current attributes and children instead of accepting incoming DOM updates. See [Preserving client-owned DOM](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md#preserving-client-owned-dom) for guidance and caveats.
+
 ## Cascade Layers
 
 Remix UI emits generated `css(...)` rules under the `rmx` cascade layer. Unlayered CSS outranks layered CSS, so use explicit layer order when mixing Remix UI with global styles.

package/src/ui/dev/refresh.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui/dev/refresh'

package/src/ui/server/README.md

@@ -23,6 +23,7 @@ Renders a component tree to a streaming response. The initial HTML is sent immed
 
 ```tsx
 import { renderToStream } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
 
 let stream = renderToStream(<App />, {
   frameSrc: request.url,
@@ -31,6 +32,17 @@ let stream = renderToStream(<App />, {
     let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
     return fetchHtml(frameUrl)
   },
+  async resolveClientEntry(entryId, component) {
+    let [href, preloads] = await Promise.all([
+      assetServer.getHref(entryId),
+      assetServer.getPreloads(entryId),
+    ])
+    return {
+      href,
+      exportName: entryId.split('#')[1] || component.name,
+      preloads,
+    }
+  },
   onError(error) {
     console.error(error)
   },
@@ -47,6 +59,7 @@ return new Response(stream, {
 - **`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.
+- **`resolveClientEntry(entryId, component)`** - Resolves the public module URL, export name, and optional module preload hrefs for a hydrated client entry.
 - **`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.

package/src/ui/test/README.md

@@ -1,104 +1,195 @@
 # Test
 
-When writing tests, use `root.flush()` to synchronously execute all pending updates and tasks. This ensures the DOM and component state are fully synchronized before making assertions.
+Use `render` from `remix/ui/test` as the primary way to test components in a live browser through a `remix/test` "browser" test (`*.test.browser.tsx`). It creates a DOM container, renders and flushes the initial component tree, and returns helpers for querying, interacting with, and cleaning up the rendered output.
 
-## Basic Testing Pattern
-
-The main use case is flushing after events that call `handle.update()`. Since updates are asynchronous, you need to flush to ensure the DOM reflects the changes:
+## Rendering Components
 
 ```tsx
+import { expect } from 'remix/assert'
+import { describe, it } from 'remix/test'
+import { on, type Handle } from 'remix/ui'
+import { render } from 'remix/ui/test'
+
 function Counter(handle: Handle) {
   let count = 0
 
   return () => (
-    <button
-      mix={[
-        on('click', () => {
-          count++
-          handle.update()
-        }),
-      ]}
-    >
-      Count: {count}
-    </button>
+    <div>
+      <button
+        data-action="increment"
+        mix={[
+          on('click', () => {
+            count++
+            handle.update()
+          }),
+        ]}
+      >
+        Increment
+      </button>
+      <output data-testid="count">{count}</output>
+    </div>
   )
 }
 
-// In your test
-let container = document.createElement('div')
-let root = createRoot(container)
+describe('Counter', () => {
+  it('increments the count', async (t) => {
+    let { $, act, cleanup } = render(<Counter />)
+    t.after(cleanup)
 
-root.render(<Counter />)
-root.flush() // Ensure initial render completes
+    expect($('[data-testid="count"]')?.textContent).toBe('0')
 
-let button = container.querySelector('button')
-button.click() // Triggers handle.update()
-root.flush() // Flush to apply the update
+    await act(() => $('[data-action="increment"]')?.click())
 
-expect(container.textContent).toBe('Count: 1')
+    expect($('[data-testid="count"]')?.textContent).toBe('1')
+  })
+})
 ```
 
-## Why Flush After Initial Render?
+The initial render is already flushed, so the DOM and event listeners are ready when `render`
+returns. Wrap interactions that may update component state in `act` and always await it. `act`
+waits for the callback and then flushes pending component updates before the next assertion.
+
+### Testing Async Operations
 
-You should also flush after the initial `root.render()` to ensure event listeners are attached and the DOM is ready for interaction:
+When an interaction starts an async operation, await that operation inside `act` so updates queued
+after it resolves are flushed before making assertions:
 
 ```tsx
-let root = createRoot(container)
-root.render(<MyComponent />)
-root.flush() // Event listeners now attached
+function UserLoader(handle: Handle<{ loadUser(): Promise<{ name: string }> }>) {
+  let name = 'No user loaded'
 
-// Safe to interact
-container.querySelector('button').click()
+  return () => (
+    <div>
+      <button
+        mix={[
+          on('click', async () => {
+            let user = await handle.props.loadUser()
+            name = user.name
+            handle.update()
+          }),
+        ]}
+      >
+        Load user
+      </button>
+      <output>{name}</output>
+    </div>
+  )
+}
+
+it('loads a user', async (t) => {
+  let userPromise = Promise.resolve({ name: 'Ada' })
+  let { $, act, cleanup } = render(<UserLoader loadUser={() => userPromise} />)
+  t.after(cleanup)
+
+  await act(async () => {
+    $('button')?.click()
+    await userPromise
+  })
+
+  expect($('output')?.textContent).toBe('Ada')
+})
 ```
 
-## Testing Async Operations
+### Querying Rendered Output
 
-For components with async operations in `queueTask`, flush after each step:
+The returned query helpers are scoped to the rendered container so you don't have to worry about false positives outside of the rendered component:
 
 ```tsx
-function AsyncLoader(handle: Handle) {
-  let data: string | null = null
-
-  handle.queueTask(async (signal) => {
-    let response = await fetch('/api/data', { signal })
-    let json = await response.json()
-    if (signal.aborted) return
-    data = json.value
-    handle.update()
-  })
+let { $, $$, container, cleanup } = render(
+  <nav>
+    <a href="/one">One</a>
+    <a href="/two">Two</a>
+  </nav>,
+)
 
-  return () => <div>{data ?? 'Loading...'}</div>
-}
+let nav = $('nav') // container.querySelector('nav')
+let links = $$('a') // container.querySelectorAll('a')
 
-// In your test (with mocked fetch)
-let root = createRoot(container)
-root.render(<AsyncLoader />)
-root.flush()
+expect(nav).toBeTruthy()
+expect(links).toHaveLength(2)
+expect(container.textContent).toContain('One')
 
-expect(container.textContent).toBe('Loading...')
+cleanup()
+```
 
-// After fetch resolves
-await waitForFetch()
-root.flush()
+Use `$` for the first matching element, `$$` for all matching elements, and `container` when a
+DOM assertion does not fit a selector.
 
-expect(container.textContent).toBe('Expected data')
+### Cleaning Up
+
+Register `cleanup` with the test context so it always runs, including when an assertion fails:
+
+```tsx
+it('renders a dialog', (t) => {
+  let { $, cleanup } = render(<Dialog />)
+  t.after(cleanup)
+
+  expect($('[role="dialog"]')).toBeTruthy()
+})
 ```
 
-## Testing Component Removal
+`cleanup` disposes the root and removes its container from the document. You can call it directly
+when a test needs to assert cleanup behavior.
+
+### Rendering Into an Existing Container
 
-Use `root.dispose()` to clean up and verify cleanup behavior:
+Pass a container when the test needs a specific DOM context:
 
 ```tsx
+let container = document.createElement('section')
+document.body.appendChild(container)
+
+let result = render(<MyComponent />, { container })
+
+expect(result.container).toBe(container)
+result.cleanup()
+```
+
+## Advanced: Flushing Manually
+
+Most component tests should use `render` and `act`. For lower-level runtime tests that need direct
+control over rendering or scheduling, use the returned `root` and call `root.flush()` after an
+operation that queues work:
+
+```tsx
+let { root, container, cleanup } = render(<MyComponent value="first" />)
+
+root.render(<MyComponent value="second" />)
+root.flush()
+
+expect(container.textContent).toContain('second')
+cleanup()
+```
+
+You can also create and manage a root directly:
+
+```tsx
+import { createRoot } from 'remix/ui'
+
+let container = document.createElement('div')
 let root = createRoot(container)
+
 root.render(<MyComponent />)
-root.flush()
+root.flush() // Complete the initial render and attach event listeners
 
-// Verify setup behavior
-expect(container.querySelector('.content')).toBeTruthy()
+container.querySelector('button')?.click()
+root.flush() // Apply updates queued by the interaction
 
-// Remove and verify cleanup
 root.dispose()
-expect(container.innerHTML).toBe('')
+```
+
+Manual flushing is also useful after an async operation resolves outside an `act` callback:
+
+```tsx
+root.render(<AsyncLoader />)
+root.flush()
+
+expect(container.textContent).toBe('Loading...')
+
+await waitForFetch()
+root.flush()
+
+expect(container.textContent).toBe('Expected data')
 ```
 
 ## See Also

package/src/ui-hmr/README.md

@@ -0,0 +1,119 @@
+# ui-hmr
+
+Hot module replacement transforms for Remix UI components, with integrations for Node and `remix/assets`.
+
+`ui-hmr` rewrites supported Remix UI component modules so they can use the standard `import.meta.hot` APIs provided by packages like [`assets`](https://github.com/remix-run/remix/tree/main/packages/assets) and [`node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr).
+
+## Features
+
+- **Stable Components** - Keep component identity stable while swapping implementations
+- **Remount Fallbacks** - Mark components stale when their setup scope changes
+- **Node Module Hooks** - Transform server component modules through Node's module customization hooks API
+- **Assets Loader** - Transform component modules for the browser through `remix/assets`
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Use `remix/ui-hmr/node` as a Node import hook for server modules:
+
+```sh
+node --import remix/node-tsx --import remix/ui-hmr/node ./server.ts
+```
+
+Use `uiHmr()` from `remix/ui-hmr/assets` with `remix/assets` for browser modules:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+import { uiHmr } from 'remix/ui-hmr/assets'
+
+let isDevelopment = process.env.NODE_ENV === 'development'
+
+let assetServer = createAssetServer({
+  basePath: '/assets',
+  fileMap: { '/app/*path': 'app/*path' },
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  allowPackages: ['remix'],
+  denyFiles: ['app/**/*.test.*'],
+  hmr: isDevelopment
+    ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+    : undefined,
+  scripts: {
+    loaders: isDevelopment ? [uiHmr()] : undefined,
+  },
+  watch: isDevelopment,
+})
+```
+
+## Direct Transforms
+
+Use the direct transform APIs when you are writing your own loader, Node module hooks, or build integration.
+
+```ts
+import { transformComponentsForBrowser } from 'remix/ui-hmr'
+
+let result = transformComponentsForBrowser(source, {
+  importSource: 'remix',
+  moduleUrl: '/assets/app/routes.tsx',
+})
+
+if (result.transformed) {
+  console.log(result.componentNames)
+}
+```
+
+`transformComponentsForBrowser(source, options)` rewrites browser component modules and emits `import.meta.hot.accept()` code for browser updates. The direct transform uses `importSource` to derive imports for the UI refresh runtime and browser HMR runtime.
+
+```ts
+import { transformComponentsForServer } from 'remix/ui-hmr'
+
+let result = transformComponentsForServer(source, {
+  importSource: 'remix',
+  moduleUrl: 'file:///app/routes.tsx',
+})
+```
+
+`transformComponentsForServer(source, options)` rewrites server component modules and registers updated component implementations for the current module URL. The direct transform uses `importSource` to derive imports for the server HMR runtime.
+
+Both transforms return:
+
+```ts
+type ComponentsHmrTransformResult = {
+  code: string
+  componentNames: string[]
+  map: string | null
+  transformed: boolean
+}
+```
+
+Pass `sourceMap: true` to generate a source map.
+
+Use `importSource` to define where injected imports come from, typically either `remix` or `@remix-run`:
+
+```ts
+transformComponentsForBrowser(source, {
+  importSource: 'remix',
+  moduleUrl: '/assets/app/routes.tsx',
+})
+
+transformComponentsForServer(source, {
+  importSource: 'remix',
+  moduleUrl: 'file:///app/routes.tsx',
+})
+```
+
+`importSource: 'remix'` generates imports from `remix/ui` and `remix/ui-hmr`. `importSource: '@remix-run'` generates imports from `@remix-run/ui` and `@remix-run/ui-hmr`. Custom import sources follow the same nested import layout.
+
+## Related Packages
+
+- [`assets`](https://github.com/remix-run/remix/tree/main/packages/assets) - Runs loaders while compiling assets
+- [`node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr) - Provides the server-side `import.meta.hot` runtime
+- [`ui`](https://github.com/remix-run/remix/tree/main/packages/ui) - Component APIs transformed by `ui-hmr`
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/ui-hmr/assets.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui-hmr/assets'

package/src/ui-hmr/node.ts

@@ -0,0 +1,3 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+import '@remix-run/ui-hmr/node'
+export {}

package/src/ui-hmr/runtime/browser.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui-hmr/runtime/browser'

package/src/ui-hmr/runtime/server.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui-hmr/runtime/server'

package/src/ui-hmr.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui-hmr'

package/dist/static-middleware.d.ts

@@ -1,2 +0,0 @@
-export * from '@remix-run/static-middleware';
-//# sourceMappingURL=static-middleware.d.ts.map

package/dist/static-middleware.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"static-middleware.d.ts","sourceRoot":"","sources":["../src/static-middleware.ts"],"names":[],"mappings":"AACA,cAAc,8BAA8B,CAAA"}