remix 3.0.0-rc.4 → 3.0.0

package/guides/09-forms-and-mutations.md

@@ -3,50 +3,275 @@ title: Forms and Mutations
 description: How native forms, action responses, validation failures, redirects, and enhanced mutations fit together.
 ---
 
-This chapter is unfinished. The sections below outline what it will cover. For working API examples, see these READMEs:
+In [Data and Validation](/data-and-validation/), we moved our albums into SQLite and defined `albumForm` to validate edits.
 
-- [Routes and controllers](../src/fetch-router/README.md)
-- [Form data middleware](../src/form-data-middleware/README.md)
-- [Form data schemas](../src/data-schema/README.md)
+Let's connect the edit form to that database. We'll parse submissions, return the form with field errors when validation fails, and save valid edits before redirecting to the album. Then we'll add pending feedback.
 
-Build the mutation as an HTML form and controller action first. Once the non-JavaScript request returns the right response, the same form can gain pending state, fetch submission, or a targeted frame reload.
+## Keep the native form
 
-## HTML-first form workflows {#html-first-form-workflows}
+Our existing `form("/albums/:albumId/edit")` route pairs two actions at the same URL. The GET `index` action loads the album for editing, and the POST `action` handler parses and saves a submission. Both belong to the controller mapped with `router.map(routes.albums.edit, albumsEditController)`.
 
-Use a real `<form method="POST">`, named native controls, and a submit button. The action URL comes from `routes.<name>.href(...)`, and the controller returns an explicit `Response` for every expected outcome.
+We'll keep a native `<form method="post">`, named inputs, and a submit button. With JavaScript disabled, the browser still sends those fields to the action and displays its response. The router's `formData()` middleware already makes the parsed body available as `context.formData`.
 
-## Form routes and controller ownership {#form-routes}
+## Load the edit form
 
-`form(path)` creates an `index` GET leaf and an `action` POST leaf by default. Keep both direct leaves in the controller mapped to that form route map, and use custom action names or methods only when the URL contract benefits from them.
+First, replace the edit controller's array lookup with a database query. The `index` action loads the album, returns `404` if it is missing, and renders the edit page:
 
-## Parse FormData once, then validate it {#parse-and-validate-form-data}
+```tsx filename=app/actions/albums/edit/controller.tsx lines=[3,9-14]
+import { createController } from "remix/router";
 
-Install `formData()` before middleware that depends on form fields, read `context.get(FormData)`, and parse with a `remix/data-schema/form-data` schema. Treat missing fields, repeated fields, checkboxes, files, and coercion as boundary concerns rather than ad hoc action checks.
+import { albums } from "../../../data/tables.ts";
+import { routes } from "../../../routes.ts";
+import { AlbumEditPage } from "./page.tsx";
 
-## Return validation failures with the form {#validation-failures}
+export default createController(routes.albums.edit, {
+  actions: {
+    async index(context) {
+      let album = await context.db.find(albums, context.params.albumId);
+      if (album === null) return new Response("Album not found", { status: 404 });
 
-Use `parseSafe()` and render the form again with issue paths, submitted values, and a `400` status. Keep entered values and error ownership close to the fields, while avoiding password or file-value replay.
+      return context.render(<AlbumEditPage album={album} />);
+    },
+    async action(context) {
+      /* ... */
+    },
+  },
+});
+```
 
-## Redirect after a successful mutation {#post-redirect-get}
+Open `/albums/thriller/edit`. The form now starts with the album's stored values.
 
-Return a `303` redirect to the resulting page after create, update, or delete work. This prevents accidental resubmission on refresh and gives the next GET a stable URL; session flash data can carry one-request success messages.
+## Return validation failures with the form
 
-## Multiple submit intents and mutation responses {#mutation-intents-and-responses}
+The page needs to distinguish the stored album from an unsuccessful edit. Add optional `values` and `issues` props to `AlbumEditPage`:
 
-Use named submit buttons when one form has a small set of related intents. Choose the response that matches the caller: rendered HTML for an in-place failure, a redirect for normal browser success, or JSON for an endpoint genuinely consumed as data.
+```tsx filename=app/actions/albums/edit/page.tsx lines=[1,10-11,22,28,31-33,41-42,44-45,47]
+import type { Issue } from "remix/data-schema";
+import type { Handle } from "remix/component";
 
-## PUT, PATCH, and DELETE from HTML forms {#method-override-for-put-patch-and-delete}
+import type { Album } from "../../../data/tables.ts";
+import { routes } from "../../../routes.ts";
+import { Document } from "../../document.tsx";
 
-HTML forms submit GET or POST. Add a hidden `_method` field and run `methodOverride()` after `formData()` when the route contract uses PUT, PATCH, or DELETE, as the bookstore demo's RESTful form wrapper does.
+interface AlbumEditPageProps {
+  album: Album;
+  values?: { title: string; artist: string; year: string };
+  issues?: readonly Issue[];
+}
 
-## Enhance submissions without replacing the action {#enhanced-form-submissions}
+const fields = [
+  { name: "title", label: "Title" },
+  { name: "artist", label: "Artist" },
+  { name: "year", label: "Year" },
+] as const;
 
-A hydrated component may intercept submit, send `new FormData(form)` with the event's abort signal, and then navigate or reload a frame. The server action should remain correct when JavaScript fails to load or the enhancement is removed.
+export function AlbumEditPage(handle: Handle<AlbumEditPageProps>) {
+  return () => {
+    let { album, values, issues = [] } = handle.props;
 
-## Pending, optimistic, and conflicting mutations {#optimistic-ui}
+    return (
+      <Document title={`Edit ${album.title} — Albums`}>
+        <main>
+          <h1>Edit {album.title}</h1>
+          {issues.length > 0 && <p role="alert">Please correct the fields below.</p>}
+          <form method="post" action={routes.albums.edit.action.href({ albumId: album.id })}>
+            {fields.map(({ name, label }) => {
+              let issue = issues.find((issue) => issue.path?.[0] === name);
+              let inputId = `album-${name}`;
+              let errorId = `${inputId}-error`;
 
-Track the attempted operation in setup scope to disable duplicate controls and render pending or optimistic state. Reconcile with the returned response, roll back failures, and use app-owned revisions or preconditions when concurrent writes can conflict.
+              return (
+                <div key={name}>
+                  <label htmlFor={inputId}>{label}</label>
+                  <input
+                    id={inputId}
+                    name={name}
+                    defaultValue={values?.[name] ?? String(album[name])}
+                    inputMode={name === "year" ? "numeric" : undefined}
+                    required
+                    aria-invalid={issue ? true : undefined}
+                    aria-describedby={issue ? errorId : undefined}
+                  />
+                  {issue && <p id={errorId}>{issue.message}</p>}
+                </div>
+              );
+            })}
+            <button type="submit">Save album</button>
+          </form>
+        </main>
+      </Document>
+    );
+  };
+}
+```
 
-## When to return JSON {#resource-routes-and-json-endpoints}
+The inputs use the stored album initially and preserve submitted `values` after validation fails. Each field displays its first validation issue, linked to the input with `aria-describedby`.
 
-Use JSON for autocomplete, polling, isolated widgets, APIs, and inter-service calls. Do not create a parallel JSON mutation layer for a form that already has a useful HTML response and redirect path.
+## Parse and save the submitted form
+
+Pass `context.formData` to `s.parseSafe(albumForm, context.formData)` in the edit action. When `parsed.success` is false, validation errors are available in `parsed.issues`. On success, `parsed.value` contains the validated fields, with trimmed text and a numeric year.
+
+Update the controller to load the album from SQLite, render invalid submissions with their errors, and save validated edits:
+
+```tsx filename=app/actions/albums/edit/controller.tsx lines=[5,19-20,30-33,36-43]
+import * as s from "remix/data-schema";
+import { redirect } from "remix/response/redirect";
+import { createController } from "remix/router";
+
+import { albums } from "../../../data/tables.ts";
+import { routes } from "../../../routes.ts";
+import { AlbumEditPage } from "./page.tsx";
+import { albumForm } from "./schema.ts";
+
+export default createController(routes.albums.edit, {
+  actions: {
+    async index(context) {
+      let album = await context.db.find(albums, context.params.albumId);
+      if (album === null) return new Response("Album not found", { status: 404 });
+
+      return context.render(<AlbumEditPage album={album} />);
+    },
+    async action(context) {
+      let parsed = s.parseSafe(albumForm, context.formData);
+      if (!parsed.success) {
+        let album = await context.db.find(albums, context.params.albumId);
+        if (album === null) return new Response("Album not found", { status: 404 });
+
+        let values = {
+          title: readText(context.formData, "title"),
+          artist: readText(context.formData, "artist"),
+          year: readText(context.formData, "year"),
+        };
+
+        return context.render(
+          <AlbumEditPage album={album} values={values} issues={parsed.issues} />,
+          { status: 400 },
+        );
+      }
+
+      try {
+        await context.db.update(albums, context.params.albumId, parsed.value);
+      } catch (error) {
+        console.error("Failed to save album:", error);
+        return new Response("Unable to save album", { status: 500 });
+      }
+
+      return redirect(routes.albums.show.href({ albumId: context.params.albumId }), 303);
+    },
+  },
+});
+
+function readText(formData: FormData, name: string): string {
+  let value = formData.get(name);
+  return typeof value === "string" ? value : "";
+}
+```
+
+`readText()` collects text for display without converting a missing entry or a file into a string. These values never become the database update. That still comes from `parsed.value`, after trimming, coercion, and validation have succeeded.
+
+The failure branch renders directly with status `400`. Redirecting back to the GET action would load the stored album again and lose the user's changes and errors. For forms with sensitive fields, choose which values to return. Leave password fields empty, and ask the user to select files again.
+
+## Redirect after saving
+
+After parsing succeeds, `db.update(...)` saves `parsed.value` to the album selected by the route's `albumId`. If the update fails, the action logs the error on the server and returns `500` without exposing database details to the browser. For other read and write helpers and their error behavior, see the [`data-table` overview](../src/data-table/README.md).
+
+After a successful save, the action returns `303 See Other` with the album page's URL. The browser follows that redirect with a GET:
+
+```txt
+POST /albums/thriller/edit
+  → update the album
+  → 303 Location: /albums/thriller
+GET /albums/thriller
+  → render the saved album
+```
+
+Refreshing the resulting page repeats the GET instead of submitting the edit again.
+
+If the destination should display “Album saved,” session flash data can carry that message across the redirect. We'll add sessions in [Auth, Sessions, and Security](/auth-sessions-security/).
+
+## Add pending feedback
+
+With the app's browser runtime running, Remix handles the form submission as a navigation. It renders validation responses into the page and follows redirects after a successful save.
+
+In [Start Here](/start-here/), we hydrated the whole form and set pending state when its submit event fired. Here, the button can follow the containing frame's reload events, which tell us when the navigation starts and when it finishes.
+
+We can show progress by hydrating just the save button. Put it in the edit action's `public/` directory:
+
+```tsx filename=app/actions/albums/edit/public/save-button.tsx
+import { clientEntry } from "remix/component";
+import type { Handle } from "remix/component";
+
+export const SaveButton = clientEntry(import.meta.url, function SaveButton(handle: Handle) {
+  let pending = false;
+
+  handle.frame.addEventListener(
+    "reloadStart",
+    () => {
+      pending = true;
+      handle.update();
+    },
+    { signal: handle.signal },
+  );
+
+  handle.frame.addEventListener(
+    "reloadComplete",
+    () => {
+      pending = false;
+      handle.update();
+    },
+    { signal: handle.signal },
+  );
+
+  return () => (
+    <button type="submit" disabled={pending}>
+      {pending ? "Saving…" : "Save album"}
+    </button>
+  );
+});
+```
+
+Back in `page.tsx`, import `SaveButton` and replace the plain submit button:
+
+```tsx filename=app/actions/albums/edit/page.tsx
+import { SaveButton } from "./public/save-button.tsx";
+
+// Inside AlbumEditPage's render function:
+<form method="post" action={routes.albums.edit.action.href({ albumId: album.id })}>
+  {/* Keep the existing fields and validation messages. */}
+  <SaveButton />
+</form>;
+```
+
+The button listens to its containing frame: `reloadStart` disables it and shows “Saving…”, and `reloadComplete` restores it after the navigation settles, including a validation response or request failure. Passing `handle.signal` removes the listeners when the component is removed.
+
+## Use other HTTP methods when the route calls for them
+
+Our edit route works with POST. If your app instead exposes a PATCH update route, HTML forms need a method override because their submission methods are GET and POST.
+
+Change the edit route's action method with `form("/albums/:albumId/edit", { formMethod: "PATCH" })`, and add this hidden field inside its existing POST form:
+
+```html
+<input type="hidden" name="_method" value="PATCH" />
+```
+
+Install method override in the router's middleware stack, immediately after form parsing:
+
+```ts lines=[2,10]
+// In app/router.ts:
+import { methodOverride } from "remix/middleware/method-override";
+
+// Keep the other middleware and controller mappings:
+export const router = createRouter({
+  middleware: [
+    staticFiles("./public", { index: false }),
+    loadDatabase(),
+    formData(),
+    methodOverride(),
+    render({ assets }),
+  ],
+});
+```
+
+The browser sends POST. After parsing `_method`, the middleware sets `context.method` to PATCH before route matching. The same controller's `action` now matches that PATCH route. Installing method override on the controller would be too late to select the route. PUT and DELETE work the same way when you define matching routes.
+
+In [Auth, Sessions, and Security](/auth-sessions-security/), we'll decide who is allowed to edit an album and connect those decisions to the request's session.

package/guides/13-testing.md

@@ -13,12 +13,12 @@ This chapter starts at that boundary, then moves outward to browser component te
 
 Choose the smallest boundary that includes the behavior you want to prove:
 
-| Test boundary          | Use it for                                                           | How to test it                                                   | Runner type |
-| ---------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------- |
-| Unit test              | A data helper, schema, utility, or other isolated module             | Import it, call it, and assert on the result                     | `server`    |
-| Router test            | An action, response, middleware, session, or database-backed request | Send a request through `router.fetch(...)`                       | `server`    |
-| Browser component test | A component event, DOM update, or browser API                        | Render the component with `remix/ui/test`'s `render()` helper    | `browser`   |
-| End-to-end test        | Navigation or a complete browser/server flow                         | Run the router behind a test server and drive it with Playwright | `e2e`       |
+| Test boundary          | Use it for                                                           | How to test it                                                       | Runner type |
+| ---------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------- |
+| Unit test              | A data helper, schema, utility, or other isolated module             | Import it, call it, and assert on the result                         | `server`    |
+| Router test            | An action, response, middleware, session, or database-backed request | Send a request through `router.fetch(...)`                           | `server`    |
+| Browser component test | A component event, DOM update, or browser API                        | Render the component with `remix/component/test`'s `render()` helper | `browser`   |
+| End-to-end test        | Navigation or a complete browser/server flow                         | Run the router behind a test server and drive it with Playwright     | `e2e`       |
 
 A controller that returns the wrong status belongs in a router test. A submit button that does not enter its pending state belongs in a browser component test. Use an end-to-end test when browser and server behavior must work together, such as submitting a form and following its redirect to the updated page.
 
@@ -219,8 +219,8 @@ npx playwright install
 Consider a small client component that tracks whether an album is a favorite:
 
 ```tsx filename=app/actions/albums/public/favorite-button.tsx
-import { clientEntry, on } from "remix/ui";
-import type { Handle } from "remix/ui";
+import { clientEntry, on } from "remix/component";
+import type { Handle } from "remix/component";
 
 export const FavoriteButton = clientEntry(
   import.meta.url,
@@ -247,12 +247,12 @@ export const FavoriteButton = clientEntry(
 );
 ```
 
-`render(...)` from [`remix/ui/test`](../src/ui/test/README.md) mounts the component, flushes its initial render, and returns helpers for querying and interacting with the DOM:
+`render(...)` from [`remix/component/test`](../src/component/test/README.md) mounts the component, flushes its initial render, and returns helpers for querying and interacting with the DOM:
 
 ```tsx filename=app/actions/albums/favorite-button.test.browser.tsx
 import * as assert from "remix/assert";
 import { describe, it } from "remix/test";
-import { render } from "remix/ui/test";
+import { render } from "remix/component/test";
 
 import { FavoriteButton } from "./public/favorite-button.tsx";
 

package/guides/14-cli-and-tooling.md

@@ -13,7 +13,7 @@ The installed `remix` package provides the CLI and the runtime subpaths used by
 
 ## Create an app with remix new {#remix-new}
 
-Use `npx remix@next new <target-dir>` before the package is installed locally, or `remix new <target-dir>` afterward. Cover `--app-name`, `--force`, the generated `app/actions` layout, and the scripts in the starter `package.json`.
+Use `npx remix new <target-dir>` before the package is installed locally, or `remix new <target-dir>` afterward. Cover `--app-name`, `--force`, the generated `app/actions` layout, and the scripts in the starter `package.json`.
 
 ## Inspect route ownership with remix routes {#remix-routes}
 
@@ -37,7 +37,7 @@ Cover `remix help`, command-level `--help`, `remix version` and `--version`, glo
 
 ## TypeScript and JSX setup {#typescript-and-jsx-setup}
 
-Explain the generated `NodeNext` module settings, `.ts` extensions in relative imports, type-only imports, `jsx: react-jsx`, and `jsxImportSource: remix/ui`. Keep `tsc --noEmit` as a separate typecheck because runtime transformation is not type checking.
+Explain the generated `NodeNext` module settings, `.ts` extensions in relative imports, type-only imports, `jsx: react-jsx`, and `jsxImportSource: remix/component`. Keep `tsc --noEmit` as a separate typecheck because runtime transformation is not type checking.
 
 ## Run source files with remix/node-tsx {#using-remix-node-tsx}