remix 3.0.0-beta.4 → 3.0.0-beta.6

package/src/test/README.md

@@ -12,7 +12,7 @@ A test framework for JavaScript and TypeScript projects.
 - Per-test and hook timeouts with `t.signal` abort support
 - Unified code coverage reporting across unit and E2E tests
 - Watch mode
-- Config file support (`remix-test.config.ts`)
+- Static CLI configuration through `remix.json`
 
 ## Installation
 
@@ -42,127 +42,145 @@ Run tests with the CLI:
 remix test
 ```
 
-By default, `remix test` discovers all files matching `**/*.test{,.e2e}.{ts,tsx}`. Pass one or more globs as positional arguments to override:
+By default, `remix test` discovers all files matching `**/*.test{,.browser,.e2e}.{ts,tsx}`. Pass one or more globs as positional arguments to override:
 
 ```sh
 remix test "src/**/*.test.ts"
 remix test "src/**/*.test.ts" "tests/**/*.test.tsx"
 ```
 
-Or, you may control via the `glob.test` config field/CLI arg. Each `glob.*` field accepts a single string or an array of patterns, and `--glob.*` flags can be repeated on the CLI.
+You may also repeat the `--glob.*` flags. Positional globs take precedence over `--glob.test`.
 
 ### Config File
 
-Create a `remix-test.config.ts` (or `.js`) file at the root of your project (shown with default values):
+Create an optional `remix.json` at the root of your project. It is parsed as JSONC, so comments and
+trailing commas are allowed:
+
+```jsonc
+{
+  "$schema": "https://remix.run/schemas/remix.json",
+  "test": {
+    "files": ["**/*.test{,.browser,.e2e}.{ts,tsx}"],
+    "browserFiles": ["**/*.test.browser.{ts,tsx}"],
+    "e2eFiles": ["**/*.test.e2e.{ts,tsx}"],
+    "exclude": ["node_modules/**", "dist/**"],
+    "type": ["server", "browser", "e2e"],
+    "only": ["/checkout/i"],
+
+    "concurrency": 2,
+    "pool": "forks",
+    "setup": "./test/setup.ts",
+    "watch": false,
+
+    "playwright": {
+      "echo": false,
+      "open": false,
+      "configFile": "./playwright.config.ts",
+      "projects": ["chromium", "firefox"],
+    },
 
-```ts
-import type { RemixTestConfig } from 'remix/test'
-
-export default {
-  // Browser options for E2E tests
-  browser: {
-    // Echo browser console output to the terminal
-    echo: false,
-    // Open browser (via playwright `headless:false`) and keep it open after tests
-    // complete (useful for debugging)
-    open: false,
+    "reporter": "spec",
+    "quiet": false,
+
+    "coverage": {
+      "enabled": true,
+      "dir": ".coverage",
+      "include": ["src/**"],
+      "exclude": ["src/**/*.test.ts"],
+      "statements": 80,
+      "lines": 80,
+      "branches": 80,
+      "functions": 80,
+    },
   },
+}
+```
 
-  // Max number of concurrent test workers (default `os.availableParallelism()`)
-  concurrency: 2,
-
-  // Pool for server and E2E test files ("forks", "threads")
-  pool: 'forks',
-
-  // Code coverage options
-  coverage: {
-    // Enable coverage reporting
-    enabled: true,
-    // Output directory (default: ".coverage")
-    dir: '.coverage',
-    // Glob pattern(s) to include/exclude
-    include: 'src/**',
-    exclude: 'src/**/*.test.ts',
-    // Minimum thresholds (%)
-    statements: 80,
-    lines: 80,
-    branches: 80,
-    functions: 80,
-  },
+Every field is optional. Relative paths and globs resolve from the directory containing the config
+file. Explicit CLI flags and positional globs take precedence. Repeatable flags replace configured
+arrays, and nested Playwright and coverage values merge by field.
 
-  // Glob pattern(s) identifying test files
-  glob: {
-    // All test files (default: "**/*.test{,.browser,.e2e}.{ts,tsx}").
-    test: '**/*.test{,.browser,.e2e}.ts',
-    // Browser test files (default: "**/*.test.browser.{ts,tsx}")
-    browser: '**/*.test.browser.ts',
-    // E2E test files (default: "**/*.test.e2e.{ts,tsx}")
-    e2e: '**/*.test.e2e.ts',
-  },
+`remix-test.config.ts` and `remix-test.config.js` are no longer discovered. Move their static values
+under `remix.json#test`. Move inline Playwright configuration into `playwright.config.ts` and point
+`playwright.configFile` at it. Use slash-delimited strings for regular expressions, and use CLI flags
+or package scripts for environment-specific overrides.
 
-  // Playwright configuration for E2E tests, or string path to an existing
-  // config file on disk
-  playwrightConfig: {
-    projects: [
-      { name: 'chromium', use: { browserName: 'chromium' } },
-      { name: 'firefox', use: { browserName: 'firefox' } },
-    ],
-    use: {
-      navigationTimeout: 5_000,
-      actionTimeout: 5_000,
-    },
-  },
+### CLI Options
 
-  // Playwright project(s) to run E2E tests for
-  project: 'chromium',
+Use the global `--config` flag to select another Remix config file. The flag path resolves from the
+current working directory:
 
-  // Test reporter ("spec", "files", "tap", "dot")
-  reporter: 'spec',
+```sh
+remix test --config ./config/remix.ci.json
+```
 
-  // Path to a setup module (see Setup section below)
-  setup: './test/setup.ts',
+You may specify any test setting as a CLI flag. Boolean settings have negative forms so configured
+`true` values can be disabled explicitly:
+
+| Flag                        | Short |
+| --------------------------- | ----- |
+| `--browser.echo`            |       |
+| `--no-browser.echo`         |       |
+| `--browser.open`            |       |
+| `--no-browser.open`         |       |
+| `--concurrency <n>`         | `-c`  |
+| `--coverage`                |       |
+| `--no-coverage`             |       |
+| `--coverage.dir <path>`     |       |
+| `--coverage.include`        |       |
+| `--coverage.exclude`        |       |
+| `--coverage.statements`     |       |
+| `--coverage.lines`          |       |
+| `--coverage.branches`       |       |
+| `--coverage.functions`      |       |
+| `--glob.test`               |       |
+| `--glob.browser`            |       |
+| `--glob.e2e`                |       |
+| `--glob.exclude`            |       |
+| `--playwrightConfig <path>` |       |
+| `--only <pattern>`          |       |
+| `--pool <forks\|threads>`   |       |
+| `--project <name>`          | `-p`  |
+| `--quiet`                   | `-q`  |
+| `--no-quiet`                |       |
+| `--reporter <name>`         | `-r`  |
+| `--setup <path>`            | `-s`  |
+| `--type <name>`             | `-t`  |
+| `--watch`                   | `-w`  |
+| `--no-watch`                |       |
+
+The standalone `remix-test` executable is no longer installed. Update scripts to use the main Remix CLI:
+
+```diff
+- "test": "remix-test --type server"
++ "test": "remix test --type server"
+```
 
-  // Test type(s) to run ("server", "browser", "e2e")
-  type: ['server', 'browser', 'e2e'],
+### Focusing Tests
 
-  // Watch for file changes and re-run
-  watch: false,
-} satisfies RemixTestConfig
-```
+Use `.only` to focus a suite or test while developing:
 
-### CLI Options
+```ts
+describe.only('Cart routes', () => {
+  it('loads cart items', () => {})
+})
 
-You can point to a different config file location with the `--config` flag:
+describe('Checkout routes', () => {
+  it.only('redirects anonymous users', () => {})
+})
+```
+
+Use `--only <pattern>` to focus tests from the CLI without editing source. Plain patterns are case-insensitive JavaScript regular expressions matched against suite names and full test names:
 
 ```sh
-remix test --config ./tests/config.ts
+remix test --only 'Cart routes'
+remix test --only 'Checkout routes > redirects anonymous users'
+remix test --only '/anonymous users$/'
 ```
 
-You may also specify any config field as a CLI flag which will take precedence over config file values:
-
-| Flag                        | Short     |
-| --------------------------- | --------- | --- |
-| `--browser.echo`            |           |
-| `--browser.open`            |           |
-| `--concurrency <n>`         | `-c`      |
-| `--coverage`                |           |
-| `--coverage.dir <path>`     |           |
-| `--coverage.include`        |           |
-| `--coverage.exclude`        |           |
-| `--coverage.statements`     |           |
-| `--coverage.lines`          |           |
-| `--coverage.branches`       |           |
-| `--coverage.functions`      |           |
-| `--glob.test`               |           |
-| `--glob.browser`            |           |
-| `--glob.e2e`                |           |
-| `--playwrightConfig <path>` |           |
-| `--pool <forks              | threads>` |     |
-| `--project <name>`          | `-p`      |
-| `--reporter <name>`         | `-r`      |
-| `--setup <path>`            | `-s`      |
-| `--type <name>`             | `-t`      |
-| `--watch`                   | `-w`      |
+Slash-delimited CLI and `remix.json` patterns preserve their flags, so `/pattern/` is case-sensitive and `/pattern/i` is case-insensitive. Plain string patterns are case-insensitive. Programmatic callers may also pass `RegExp` values.
+
+Full test names join nested `describe` names and the test name with `>`. For example, `describe('Cart routes', () => describe('loader', () => it('loads cart items', ...)))` has the full test name `Cart routes > loader > loads cart items`.
 
 ### Setup
 
@@ -221,12 +239,19 @@ suite('My Test Suite', () => {
 import { runRemixTest } from 'remix/test/cli'
 
 let exitCode = await runRemixTest({
-  argv: ['--type', 'server'],
+  concurrency: 1,
   cwd: process.cwd(),
+  glob: { test: 'src/**/*.test.ts' },
+  type: ['server'],
 })
 ```
 
-`runRemixTest()` returns the runner exit code. The `remix test` bin wrapper calls `process.exit()` with that code when the run finishes so open workers, browsers, or project handles cannot keep the CLI alive.
+The programmatic runner accepts structured options only; it does not discover or load configuration
+files. Programmatic callers may pass richer values such as an inline Playwright config or `RegExp`
+test-name filters. The main Remix CLI owns `remix.json` loading and passes the resolved options to the
+runner.
+
+`runRemixTest()` does not read `process.argv` or terminate the process; it returns the runner exit code. The main `remix` executable owns argument parsing and passes the final code to `process.exit()` so open workers, browsers, or project handles cannot keep the CLI alive. `@remix-run/test` does not install a standalone executable.
 
 ### Test Context
 
@@ -426,28 +451,49 @@ describe('checkout', () => {
 })
 ```
 
-Configure Playwright (browsers, timeouts, viewport, etc.) via `playwrightConfig` in your config file:
+Configure Playwright's browsers, timeouts, viewport, and other executable settings in
+`playwright.config.ts`:
 
 ```ts
-export default {
-  playwrightConfig: {
-    projects: [
-      { name: 'chromium', use: { browserName: 'chromium' } },
-      { name: 'firefox', use: { browserName: 'firefox' } },
-      { name: 'webkit', use: { browserName: 'webkit' } },
-    ],
-    use: {
-      navigationTimeout: 5_000,
-      actionTimeout: 5_000,
-    },
+import { defineConfig } from 'playwright/test'
+
+export default defineConfig({
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+    { name: 'firefox', use: { browserName: 'firefox' } },
+    { name: 'webkit', use: { browserName: 'webkit' } },
+  ],
+  use: {
+    navigationTimeout: 5_000,
+    actionTimeout: 5_000,
   },
+})
+```
 
-  // Or, point to an existing playwright config file
-  // playwrightConfig: './playwright.config.ts'
-} satisfies RemixTestConfig
+Reference it from `remix.json` when it is not at the default location:
+
+```jsonc
+{
+  "test": {
+    "playwright": {
+      "configFile": "./playwright.config.ts",
+    },
+  },
+}
 ```
 
-Set `browser.open: true` to keep the browser open after tests finish — useful for debugging failures.
+Set `test.playwright.open` to `true`, or pass `--browser.open`, to keep the browser open after tests
+finish—useful for debugging failures.
+
+## Related Packages
+
+- [`assert`](https://github.com/remix-run/remix/tree/main/packages/assert) provides assertions that work in server and browser tests.
+- [`ui`](https://github.com/remix-run/remix/tree/main/packages/ui) provides the `remix/ui/test` browser rendering utilities.
+
+## Related Work
+
+- [Playwright](https://playwright.dev) provides the browser automation used by browser and E2E tests.
+- [Node.js test runner](https://nodejs.org/api/test.html) provides prior art for the test framework API and reporting model.
 
 ## License
 

package/src/ui/README.md

@@ -1,15 +1,14 @@
 # ui
 
-Runtime UI primitives for Remix apps, including the component runtime, server rendering, frame hydration, reusable mixins, first-party components, and theme tokens.
+Runtime UI primitives for Remix apps, including the component runtime, server rendering, frame hydration, reusable mixins, and headless first-party behavior primitives.
 
 ## 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
-- First-party components such as buttons, menus, listboxes, popovers, and selects
-- Fixed typed `theme` contract whose leaves resolve to `var(--rmx-...)`
-- `createTheme()` and `createGlyphSheet()` utilities for shared app styling and glyphs
+- Headless behavior primitives for controls such as menus, listboxes, popovers, selects, and comboboxes
+- Lower-level utilities for keyboard events, typeahead search, refs, attributes, and CSS transition timing
 
 ## Installation
 
@@ -19,188 +18,148 @@ npm i remix
 
 ## Usage
 
-Define your app theme once:
+Compose behavior primitives with your own markup and styles:
 
 ```tsx
-import { createTheme } from 'remix/ui'
-
-let Theme = createTheme({
-  space: {
-    none: '0px',
-    px: '1px',
-    xs: '2px',
-    sm: '4px',
-    md: '8px',
-    lg: '12px',
-    xl: '16px',
-    xxl: '24px',
-  },
-  radius: {
-    none: '0px',
-    sm: '4px',
-    md: '8px',
-    lg: '12px',
-    xl: '16px',
-    full: '9999px',
-  },
-  fontSize: {
-    xxxs: '10px',
-    xxs: '11px',
-    xs: '12px',
-    sm: '14px',
-    md: '16px',
-    lg: '18px',
-    xl: '20px',
-    xxl: '28px',
-  },
-  lineHeight: {
-    tight: '1.2',
-    normal: '1.5',
-    relaxed: '1.7',
-  },
-  fontWeight: {
-    normal: '400',
-    medium: '500',
-    semibold: '600',
-    bold: '700',
-  },
-  shadow: {
-    xs: '0 1px 2px rgb(0 0 0 / 0.05)',
-    sm: '0 1px 3px rgb(0 0 0 / 0.10)',
-    md: '0 4px 10px rgb(0 0 0 / 0.12)',
-    lg: '0 10px 30px rgb(0 0 0 / 0.16)',
-    xl: '0 20px 50px rgb(0 0 0 / 0.20)',
-  },
-  zIndex: {
-    dropdown: '1000',
-    popover: '1100',
-    sticky: '1200',
-    overlay: '1300',
-    modal: '1400',
-    toast: '1500',
-    tooltip: '1600',
-  },
-  surface: {
-    lvl0: '#ffffff',
-    lvl1: '#f8fafc',
-    lvl2: '#f1f5f9',
-    lvl3: '#e5edf7',
-    lvl4: '#dbe6f4',
-  },
-  colors: {
-    text: {
-      primary: '#111827',
-      secondary: '#374151',
-      muted: '#6b7280',
-      link: '#2563eb',
-    },
-    border: {
-      subtle: '#e5e7eb',
-      default: '#d1d5db',
-      strong: '#9ca3af',
-    },
-    focus: {
-      ring: '#3b82f6',
-    },
-    overlay: {
-      scrim: 'rgb(0 0 0 / 0.45)',
-    },
-    action: {
-      primary: {
-        background: '#2563eb',
-        backgroundHover: '#1d4ed8',
-        backgroundActive: '#1e40af',
-        foreground: '#ffffff',
-        border: '#2563eb',
-      },
-      secondary: {
-        background: '#ffffff',
-        backgroundHover: '#f8fafc',
-        backgroundActive: '#f1f5f9',
-        foreground: '#111827',
-        border: '#d1d5db',
-      },
-      danger: {
-        background: '#dc2626',
-        backgroundHover: '#b91c1c',
-        backgroundActive: '#991b1b',
-        foreground: '#ffffff',
-        border: '#dc2626',
-      },
-    },
-  },
+import { css } from 'remix/ui'
+import * as popover from 'remix/ui/popover'
+
+let triggerCss = css({
+  border: '1px solid #d1d5db',
+  borderRadius: '6px',
+  padding: '6px 10px',
 })
-```
 
-Render the theme once near the top of your document:
+let surfaceCss = css({
+  background: 'white',
+  border: '1px solid #d1d5db',
+  borderRadius: '6px',
+  padding: '8px',
+})
 
-```tsx
-import type { Handle, RemixNode } from 'remix/ui'
+function ViewOptions() {
+  let open = false
 
-function Layout(handle: Handle<{ children: RemixNode }>) {
   return () => (
-    <html>
-      <head>
-        <Theme />
-      </head>
-      <body>{handle.props.children}</body>
-    </html>
+    <popover.Context>
+      <button
+        mix={[triggerCss, popover.anchor({ placement: 'bottom-end' }), popover.focusOnHide()]}
+        onClick={() => {
+          open = true
+        }}
+        type="button"
+      >
+        View options
+      </button>
+      <div
+        mix={[
+          surfaceCss,
+          popover.surface({
+            open,
+            onHide() {
+              open = false
+            },
+          }),
+        ]}
+      >
+        Panel content
+      </div>
+    </popover.Context>
   )
 }
 ```
 
-Consume the shared token contract from app code and first-party components:
+Button styling is available as a composable mixin:
 
 ```tsx
-import { css } from 'remix/ui'
-import { theme } from 'remix/ui'
-
-let card = css({
-  backgroundColor: theme.surface.lvl0,
-  color: theme.colors.text.primary,
-  border: `1px solid ${theme.colors.border.subtle}`,
-  borderRadius: theme.radius.md,
-  paddingInline: theme.space.md,
-  paddingBlock: theme.space.sm,
+import button from 'remix/ui/button'
+
+function Actions() {
+  return () => <button mix={button({ tone: 'primary' })}>Create project</button>
+}
+```
+
+## Frame Navigation
+
+Configure `resolveFrame` once to progressively enhance same-origin links and forms. The resolver owns the fetch request and receives native submission metadata for non-GET forms:
+
+```tsx
+import type { ResolveFrameOptions } from 'remix/ui'
+import { run } from 'remix/ui'
+
+let app = run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+  async resolveFrame(src, options) {
+    return fetch(src, {
+      headers: { Accept: 'text/html', 'X-Remix-Frame': 'true' },
+      method: options?.method,
+      body: getRequestBody(options),
+      signal: options?.signal,
+    })
+  },
 })
 
-<div mix={card} />
+function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
+  let formData = options?.formData
+  if (!formData) return
+  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
+}
+
+await app.ready()
 ```
 
-Render shared glyphs separately from the theme styles:
+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 type { Handle, RemixNode } from 'remix/ui'
-import { Button } from 'remix/ui/button'
-import { Glyph } from 'remix/ui/glyph'
-import { RMX_01, RMX_01_GLYPHS } from 'remix/ui/theme'
+import { Frame } from 'remix/ui'
 
-function Layout(handle: Handle<{ children: RemixNode }>) {
+function AccountPage() {
   return () => (
-    <html>
-      <head>
-        <RMX_01 />
-      </head>
-      <body>
-        <RMX_01_GLYPHS />
-        <Button startIcon={<Glyph name="add" />} tone="primary">
-          New project
-        </Button>
-        {handle.props.children}
-      </body>
-    </html>
+    <>
+      <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 its built-in theme reset in `rmx-reset` and generated `css(...)` rules under `rmx`. Unlayered CSS outranks layered component CSS, so use explicit layer order when mixing Remix UI with global styles.
+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.
 
-Put layers that should lose to Remix UI before `rmx-reset` and `rmx`:
+Put layers that should lose to Remix UI before `rmx`:
 
 ```css
-@layer base, rmx-reset, rmx;
+@layer base, rmx;
 
 @layer base {
   button,