remix 3.0.0-beta.5 → 3.0.0-beta.6

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'