remix 3.0.0-rc.4 → 3.0.0

package/guides/06-streaming-ui-with-frames.md

@@ -68,8 +68,8 @@ export default createController(routes.albums, {
 Now the page can render that route with `Frame`:
 
 ```tsx filename=app/actions/albums/show-page.tsx
-import { Frame } from "remix/ui";
-import type { Handle } from "remix/ui";
+import { Frame } from "remix/component";
+import type { Handle } from "remix/component";
 
 import { routes } from "../../routes.ts";
 import { Document } from "../document.tsx";
@@ -148,7 +148,7 @@ response type. Normal HTML actions should use the standard `render()` middleware
 continue, such as an email preview or a small embedded fragment:
 
 ```tsx
-import { renderToString } from "remix/ui/server";
+import { renderToString } from "remix/component/server";
 
 // After loading recommendations:
 let html = await renderToString(<AlbumRecommendations albums={recommendations} />);
@@ -160,62 +160,19 @@ frames with fallbacks arrive after the initial HTML.
 ## Resolve frames in the browser
 
 A blocking frame resolves before the browser receives the page. A frame with a fallback may still
-be pending, and any frame can reload later. Back in `app/actions/public/entry.ts`, add `resolveFrame`
-to the existing `run()` options for those requests:
+be pending, and any frame can reload later. The `run()` call in `app/actions/public/entry.ts` already
+provides a default browser resolver, so these requests need no additional configuration.
 
-```ts filename=app/actions/public/entry.ts lines=[1,9-27,29-39]
-import type { ResolveFrameOptions } from "remix/ui";
-import { run } from "remix/ui";
+The default resolver fetches same-origin HTML, follows redirects, preserves form submission methods
+and encoding, and cancels requests when a frame is removed or its request is superseded. It also
+keeps the redirect destination available so navigation can update the browser URL after a form saves.
 
-// ...
+If your app needs different request or response handling, you can provide your own `resolveFrame`
+function in the `run()` options. The [`remix/component` API overview](../src/component/README.md)
+covers the callback's arguments and return values.
 
-let app = run({
-  // ...
-
-  async resolveFrame(src, options) {
-    let headers = new Headers({ Accept: "text/html", "X-Remix-Frame": "true" });
-    if (options?.target) headers.set("X-Remix-Target", options.target);
-
-    let response = await fetch(src, {
-      body: getRequestBody(options),
-      credentials: "same-origin",
-      headers,
-      method: options?.method,
-      mode: "same-origin",
-      signal: options?.signal,
-    });
-
-    if (!response.ok) {
-      throw new Error(`Frame request failed with status ${response.status}`);
-    }
-
-    return response.body ?? response.text();
-  },
-});
-
-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;
-}
-```
-
-The default resolver only makes same-origin requests, including redirects. This custom resolver
-keeps that restriction with `mode: "same-origin"`; omit it only when the application explicitly
-trusts a cross-origin source. Remix does not sanitize returned HTML before reconciling it into the
-current document, and same-origin user-generated HTML is not implicitly safe. Sanitize untrusted
-content before returning it.
-
-Pass `options.signal` to `fetch()` instead of letting a removed or superseded frame request
-continue. GET forms already include their values in `src`. For non-GET forms, the resolver receives
-the browser's `FormData`, method, and encoding. This example preserves URL-encoded and multipart
-form bodies; the resolver remains the place to apply other encoding or `_method` conventions.
+Remix does not sanitize returned HTML before reconciling it into the current document, and
+same-origin user-generated HTML is not implicitly safe. Sanitize untrusted content before returning it.
 
 ## Name and reload frames {#frames-and-partial-server-rendered-ui}
 
@@ -245,9 +202,8 @@ setup state and receive current server props.
 
 ## Navigate a frame with a form
 
-Once `run({ resolveFrame })` starts, an eligible same-origin form follows the same frame navigation
-path as a link. This GET form reloads the recommendations frame without a client entry or submit
-handler:
+Once `run()` starts, an eligible same-origin form follows the same frame navigation path as a link.
+This GET form reloads the recommendations frame without a client entry or submit handler:
 
 ```tsx
 <form
@@ -265,11 +221,12 @@ frame, `data-rmx-src` can provide a different request URL for that named frame,
 `data-rmx-reset-scroll="false"` preserves the current scroll position, and `data-rmx-document` opts out of
 interception. `data-rmx-history="push|replace"` controls how the navigation updates history.
 
-GET controls are already encoded in the destination URL. For non-GET forms, `resolveFrame` receives
-`formData`, `method`, and `encType`. The action should return HTML for the targeted frame when it
-receives a frame request, while keeping its normal document response or redirect for unenhanced
-submissions. Non-GET submissions to the current URL replace that history entry; GET submissions and
-submissions to a different URL push one. The `data-rmx-history` attribute overrides those defaults.
+GET controls are already encoded in the destination URL. For non-GET forms, the default resolver
+sends the form's body with its method and encoding. The action should return HTML for the targeted
+frame when it receives a frame request, while keeping its normal document response or redirect for
+unenhanced submissions. Non-GET submissions to the current URL replace that history entry; GET
+submissions and submissions to a different URL push one. The `data-rmx-history` attribute overrides
+those defaults.
 
 ## Coordinate a mutation and a separate frame reload {#coordinating-forms-fetches-frame-reloads-and-navigation}
 
@@ -277,7 +234,7 @@ Start with a form whose action works without browser JavaScript. A client entry
 same submission, send its `FormData`, and reload a different route after the action succeeds:
 
 ```tsx
-import { on } from "remix/ui";
+import { on } from "remix/component";
 
 // Inside a client-entry component's render function:
 <form
@@ -308,7 +265,7 @@ import { on } from "remix/ui";
 
 This custom handler is useful because the mutation response and recommendations frame are two
 different requests. When the form action itself returns the HTML that belongs in the target frame,
-prefer `data-rmx-target` and let the runtime submit it through `resolveFrame`.
+prefer `data-rmx-target` and let the runtime submit it.
 
 The handler above keeps the mutation in its existing action and the recommendations HTML in its
 existing `GET` action. The browser component coordinates the two requests without duplicating either
@@ -345,15 +302,16 @@ Add `data-rmx-history="replace"` when it should replace the current history entr
 
 ## Handle failures and cancellation
 
-The server renderer's `onError` and the browser app's `error` event are reporting hooks. The app's
-frame resolver decides whether a non-success response should become bounded HTML for that region or
-an error reported through those hooks.
+The server renderer's `onError` and the browser app's `error` event are reporting hooks. The default
+browser resolver renders HTML validation responses such as `400`, but reports server errors (`500`
+and above) and non-HTML error responses through the browser app's `error` event.
 
 If a deferred frame fails after its fallback has been sent, the server cannot replace the whole page
 with a new error response. Keep the fallback useful, report the error, and let the surrounding page
 continue when that is safe.
 
-Pass `request.signal` through server frame work and the browser resolver's signal through `fetch()`.
+Pass `request.signal` through server frame work. The default browser resolver forwards its cancellation
+signal to `fetch()`; a custom resolver should do the same.
 [Errors and Cancellation](/errors-and-cancellation/) covers reporting policy, while
 [Production](/production/) covers disconnects, compression, and other deployment concerns.
 

package/guides/07-animation.md

@@ -1,6 +1,6 @@
 ---
 title: Animation
-description: The CSS-first animation model and Remix UI helpers for motion that respects rendering state.
+description: The CSS-first animation model and Remix component helpers for motion that respects rendering state.
 ---
 
 ## CSS-first visual states {#css-first-visual-states}
@@ -8,8 +8,8 @@ description: The CSS-first animation model and Remix UI helpers for motion that
 Start with CSS when the browser already owns the state. Hover, focus, active, checked, open, selected, and reduced-motion states do not need JavaScript state unless your render output also depends on them.
 
 ```tsx filename=app/ui/pressable-card.tsx
-import { css } from "remix/ui";
-import type { Handle, RemixNode } from "remix/ui";
+import { css } from "remix/component";
+import type { Handle, RemixNode } from "remix/component";
 
 export function PressableCard(handle: Handle<{ children: RemixNode }>) {
   return () => (
@@ -42,10 +42,16 @@ const cardStyle = css({
 
 Use Remix animation helpers when the motion depends on rendering state: a node enters, a node exits, a keyed item moves, or an event needs an interruptible animation.
 
+The animation helpers are provided by `@remix-run/ui`. This package is currently unstable and versioned independently. It is not available through the `remix` package, so install it separately:
+
+```sh
+npm i remix @remix-run/ui
+```
+
 ```tsx
-import { createMixin, css, on } from "remix/ui";
-import type { Handle } from "remix/ui";
-import { spring } from "remix/ui/animation";
+import { createMixin, css, on } from "remix/component";
+import type { Handle } from "remix/component";
+import { spring } from "@remix-run/ui/animation";
 
 export function PressStateDemo(handle: Handle) {
   let pressed = false;
@@ -123,9 +129,9 @@ const pressableStyles = css({
 `animateEntrance(...)` runs when a host node is inserted. `animateExit(...)` lets a removed node stay in the DOM until its exit animation finishes.
 
 ```tsx filename=app/ui/public/notice.tsx
-import { clientEntry, css, on } from "remix/ui";
-import { animateEntrance, animateExit, spring } from "remix/ui/animation";
-import type { Handle } from "remix/ui";
+import { clientEntry, css, on } from "remix/component";
+import { animateEntrance, animateExit, spring } from "@remix-run/ui/animation";
+import type { Handle } from "remix/component";
 
 export const Notice = clientEntry(import.meta.url, function Notice(handle: Handle) {
   let visible = true;
@@ -180,9 +186,9 @@ Keep keys stable when toggling between related elements. A stable key tells Remi
 Pass `true` for the default opacity animation or `false` to disable a mixin without changing the surrounding `mix` array. `animateEntrance({ initial: false })` skips the first insertion for a key but still animates later insertions. If the same keyed element returns before its exit finishes, Remix reclaims that DOM node and animates it back toward its rendered styles.
 
 ```tsx
-import { css, on } from "remix/ui";
-import type { Handle } from "remix/ui";
-import { animateEntrance, animateExit, spring } from "remix/ui/animation";
+import { css, on } from "remix/component";
+import type { Handle } from "remix/component";
+import { animateEntrance, animateExit, spring } from "@remix-run/ui/animation";
 
 export function NoticePresenceDemo(handle: Handle) {
   let visible = true;
@@ -257,9 +263,9 @@ const noticeStyles = css({
 `animateLayout(...)` measures a host node before and after a render, then animates the visual delta. This is the right tool for sorted lists, expanding cards, and elements that move because layout changed.
 
 ```tsx filename=app/ui/public/reorder-list.tsx
-import { clientEntry, css, on } from "remix/ui";
-import { animateLayout, spring } from "remix/ui/animation";
-import type { Handle } from "remix/ui";
+import { clientEntry, css, on } from "remix/component";
+import { animateLayout, spring } from "@remix-run/ui/animation";
+import type { Handle } from "remix/component";
 
 const initialItems = ["Design", "Build", "Review"];
 
@@ -309,9 +315,9 @@ const itemStyle = css({
 Layout animation includes size projection by default. Pass `size: false` when only position should animate and scaling the element's contents would look wrong.
 
 ```tsx
-import { css } from "remix/ui";
-import type { Handle } from "remix/ui";
-import { animateLayout, spring } from "remix/ui/animation";
+import { css } from "remix/component";
+import type { Handle } from "remix/component";
+import { animateLayout, spring } from "@remix-run/ui/animation";
 
 export function ReorderingDemo(handle: Handle) {
   let order = initialOrder;
@@ -388,9 +394,9 @@ const itemStyles = css({
 `spring()` returns an iterator decorated for CSS transitions and Web Animations. Stringify it in CSS, spread it into animation options, or iterate it for custom JavaScript animation.
 
 ```tsx filename=app/ui/public/bouncy-switch.tsx
-import { clientEntry, css, on } from "remix/ui";
-import { spring } from "remix/ui/animation";
-import type { Handle } from "remix/ui";
+import { clientEntry, css, on } from "remix/component";
+import { spring } from "@remix-run/ui/animation";
+import type { Handle } from "remix/component";
 
 export const BouncySwitch = clientEntry(import.meta.url, function BouncySwitch(handle: Handle) {
   let enabled = true;
@@ -439,7 +445,7 @@ const thumbStyle = css({
 Use `tween(...)` when you need a time-based value loop rather than CSS or WAAPI timing.
 
 ```ts filename=app/ui/public/count-up.ts
-import { easings, tween } from "remix/ui/animation";
+import { easings, tween } from "@remix-run/ui/animation";
 
 export function countUp(from: number, to: number, onValue: (value: number) => void) {
   let animation = tween({ from, to, duration: 300, curve: easings.easeOut });
@@ -461,10 +467,10 @@ export function countUp(from: number, to: number, onValue: (value: number) => vo
 Prefer CSS transitions and animation mixins for ordinary UI. Use `tween` for canvas, custom counters, or values that are not CSS properties.
 
 ```tsx
-import { css, on, ref } from "remix/ui";
-import type { Handle } from "remix/ui";
-import { spring } from "remix/ui/animation";
-import type { SpringPreset } from "remix/ui/animation";
+import { css, on, ref } from "remix/component";
+import type { Handle } from "remix/component";
+import { spring } from "@remix-run/ui/animation";
+import type { SpringPreset } from "@remix-run/ui/animation";
 
 import { dragVelocityEvents } from "./gallery/drag-release.ts";
 
@@ -681,9 +687,9 @@ const hintStyle = css({
 ```
 
 ```tsx
-import { css, on } from "remix/ui";
-import type { Handle } from "remix/ui";
-import { spring } from "remix/ui/animation";
+import { css, on } from "remix/component";
+import type { Handle } from "remix/component";
+import { spring } from "@remix-run/ui/animation";
 
 export function BouncySwitchDemo(handle: Handle) {
   let isOn = true;
@@ -738,7 +744,7 @@ const thumbStyles = css({
 The UI package also keeps a gallery of smaller motion experiments. Keep this kind of broad demo in a bounded frame so it does not take over the surrounding guide page.
 
 ```tsx
-import { css, on, type Handle, type RemixNode } from "remix/ui";
+import { css, on, type Handle, type RemixNode } from "remix/component";
 import { DefaultAnimate } from "./gallery/default-animate.tsx";
 import { EnterAnimation } from "./gallery/enter.tsx";
 import { ExitAnimation } from "./gallery/exit.tsx";
@@ -937,9 +943,9 @@ Event handlers receive abort signals, and animation mixins cancel or replace in-
 For custom imperative animations, keep the current animation in setup scope and cancel it before starting the next one:
 
 ```tsx filename=app/ui/public/ripple-button.tsx
-import { clientEntry, css, on, ref } from "remix/ui";
-import { spring } from "remix/ui/animation";
-import type { Handle } from "remix/ui";
+import { clientEntry, css, on, ref } from "remix/component";
+import { spring } from "@remix-run/ui/animation";
+import type { Handle } from "remix/component";
 
 export const RippleButton = clientEntry(import.meta.url, function RippleButton(_handle: Handle) {
   let node: HTMLButtonElement;
@@ -984,8 +990,8 @@ CSS transitions are also interruptible: changing the target value while a transi
 Respect `prefers-reduced-motion` at the CSS boundary first. It works before JavaScript loads, applies to server-rendered frames, and covers static transitions.
 
 ```tsx filename=app/ui/motion-safe-panel.tsx
-import { css } from "remix/ui";
-import type { Handle, RemixNode } from "remix/ui";
+import { css } from "remix/component";
+import type { Handle, RemixNode } from "remix/component";
 
 export function MotionSafePanel(handle: Handle<{ children: RemixNode }>) {
   return () => <section mix={panelStyle}>{handle.props.children}</section>;