Merge branch 'release-next'

remix-run · Oct 16, 2023 · 779536c · 779536c
2 parents 7ce38dc + edd9ad4
commit 779536c
Show file tree

Hide file tree

Showing 46 changed files with 3,455 additions and 123 deletions.
diff --git a/contributors.yml b/contributors.yml
@@ -25,6 +25,7 @@
 - avipatel97
 - awreese
 - aymanemadidi
+- ayushmanchhabra
 - babafemij-k
 - bavardage
 - bbrowning918
@@ -52,6 +53,7 @@
 - danielberndt
 - daniilguit
 - dauletbaev
+- david-bezero
 - david-crespo
 - decadentsavant
 - DigitalNaut
@@ -236,4 +238,6 @@
 - xcsnowcity
 - yionr
 - yuleicul
+- yracnet
 - zheng-chuang
+- sgrishchenko
diff --git a/docs/components/form.md b/docs/components/form.md
@@ -5,6 +5,32 @@ new: true
 
 # `<Form>`
 
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function Form(props: FormProps): React.ReactElement;
+
+interface FormProps
+  extends React.FormHTMLAttributes<HTMLFormElement> {
+  method?: "get" | "post" | "put" | "patch" | "delete";
+  encType?:
+    | "application/x-www-form-urlencoded"
+    | "multipart/form-data"
+    | "text/plain";
+  action?: string;
+  onSubmit?: React.FormEventHandler<HTMLFormElement>;
+  preventScrollReset?: boolean;
+  relative?: "route" | "path";
+  reloadDocument?: boolean;
+  replace?: boolean;
+  state?: any;
+  unstable_viewTransition?: boolean;
+}
+```
+
+</details>
+
 The Form component is a wrapper around a plain HTML [form][htmlform] that emulates the browser for client side routing and data mutations. It is _not_ a form validation/state management library like you might be used to in the React ecosystem (for that, we recommend the browser's built in [HTML Form Validation][formvalidation] and data validation on your backend server).
 
 <docs-warning>This feature only works if using a data router, see [Picking a Router][pickingarouter]</docs-warning>
@@ -243,6 +269,12 @@ If you are using [`<ScrollRestoration>`][scrollrestoration], this lets you preve
 
 See also: [`<Link preventScrollReset>`][link-preventscrollreset]
 
+## `unstable_viewTransition`
+
+The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`. If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state].
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
 # Examples
 
 TODO: More examples
@@ -349,3 +381,5 @@ You can access those values from the `request.url`
 [scrollrestoration]: ./scroll-restoration
 [link-preventscrollreset]: ./link#preventscrollreset
 [history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
+[use-view-transition-state]: ../hooks//use-view-transition-state
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
diff --git a/docs/components/link.md b/docs/components/link.md
@@ -17,12 +17,13 @@ interface LinkProps
     React.AnchorHTMLAttributes<HTMLAnchorElement>,
     "href"
   > {
-  replace?: boolean;
-  state?: any;
   to: To;
-  reloadDocument?: boolean;
   preventScrollReset?: boolean;
   relative?: "route" | "path";
+  reloadDocument?: boolean;
+  replace?: boolean;
+  state?: any;
+  unstable_viewTransition?: boolean;
 }
 
 type To = string | Partial<Path>;
@@ -146,8 +147,57 @@ let { state } = useLocation();
 
 The `reloadDocument` property can be used to skip client side routing and let the browser handle the transition normally (as if it were an `<a href>`).
 
+## `unstable_viewTransition`
+
+The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`:
+
+```jsx
+<Link to={to} unstable_viewTransition>
+  Click me
+</Link>
+```
+
+If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state] hook (or check out the `transitioning` class and `isTransitioning` render prop in [NavLink][navlink]):
+
+```jsx
+function ImageLink(to) {
+  const isTransitioning =
+    unstable_useViewTransitionState(to);
+  return (
+    <Link to={to} unstable_viewTransition>
+      <p
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-title"
+            : "",
+        }}
+      >
+        Image Number {idx}
+      </p>
+      <img
+        src={src}
+        alt={`Img ${idx}`}
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-expand"
+            : "",
+        }}
+      />
+    </Link>
+  );
+}
+```
+
+<docs-warning>`unstable_viewTransition` only works when using a data router, see [Picking a Router][picking-a-router]</docs-warning>
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
 [link-native]: ./link-native
 [scrollrestoration]: ./scroll-restoration
 [history-replace-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState
 [history-push-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
 [history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
+[use-view-transition-state]: ../hooks//use-view-transition-state
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+[picking-a-router]: ../routers/picking-a-router
+[navlink]: ./nav-link
diff --git a/docs/components/nav-link.md b/docs/components/nav-link.md
@@ -4,7 +4,11 @@ title: NavLink
 
 # `<NavLink>`
 
-A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active" or "pending". This is useful when building a navigation menu, such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected. It also provides useful context for assistive technology like screen readers.
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active", "pending", or "transitioning". This is useful in a few different scenarios:
+
+- When building a navigation menu, such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected
+- It provides useful context for assistive technology like screen readers
+- It provides a "transitioning" value to give you finer-grained control over [View Transitions][view-transitions]
 
 ```tsx
 import { NavLink } from "react-router-dom";
@@ -42,8 +46,12 @@ The `className` prop works like a normal className, but you can also pass it a f
 ```tsx
 <NavLink
   to="/messages"
-  className={({ isActive, isPending }) =>
-    isPending ? "pending" : isActive ? "active" : ""
+  className={({ isActive, isPending, isTransitioning }) =>
+    [
+      isPending ? "pending" : "",
+      isActive ? "active" : "",
+      isTransitioning ? "transitioning" : "",
+    ].join(" ")
   }
 >
   Messages
@@ -57,10 +65,11 @@ The `style` prop works like a normal style prop, but you can also pass it a func
 ```tsx
 <NavLink
   to="/messages"
-  style={({ isActive, isPending }) => {
+  style={({ isActive, isPending, isTransitioning }) => {
     return {
       fontWeight: isActive ? "bold" : "",
       color: isPending ? "red" : "black",
+      viewTransitionName: isTransitioning ? "slide" : "",
     };
   }}
 >
@@ -74,7 +83,7 @@ You can pass a render prop as children to customize the content of the `<NavLink
 
 ```tsx
 <NavLink to="/tasks">
-  {({ isActive, isPending }) => (
+  {({ isActive, isPending, isTransitioning }) => (
     <span className={isActive ? "active" : ""}>Tasks</span>
   )}
 </NavLink>
@@ -112,4 +121,59 @@ When a `NavLink` is active it will automatically apply `<a aria-current="page">`
 
 The `reloadDocument` property can be used to skip client side routing and let the browser handle the transition normally (as if it were an `<a href>`).
 
+## `unstable_viewTransition`
+
+The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`. By default, during the transition a `transitioning` class will be added to the `<a>` element that you can use to customize the view transition.
+
+```css
+a.transitioning p {
+  view-transition-name: "image-title";
+}
+
+a.transitioning img {
+  view-transition-name: "image-expand";
+}
+```
+
+```jsx
+<NavLink to={to} unstable_viewTransition>
+  <p>Image Number {idx}</p>
+  <img src={src} alt={`Img ${idx}`} />
+</NavLink>
+```
+
+You may also use the `className`/`style` props or the render props passed to `children` to further customize based on the `isTransitioning` value.
+
+```jsx
+<NavLink to={to} unstable_viewTransition>
+  {({ isTransitioning }) => (
+    <>
+      <p
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-title"
+            : "",
+        }}
+      >
+        Image Number {idx}
+      </p>
+      <img
+        src={src}
+        alt={`Img ${idx}`}
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-expand"
+            : "",
+        }}
+      />
+    </>
+  )}
+</NavLink>
+```
+
+<docs-warning>
+Please note that this API is marked unstable and may be subject to breaking changes without a major release.
+</docs-warning>
+
 [aria-current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
diff --git a/docs/hooks/use-navigate.md b/docs/hooks/use-navigate.md
@@ -85,9 +85,20 @@ function EditContact() {
 }
 ```
 
+## `options.unstable_viewTransition`
+
+The `unstable_viewTransition` option enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`. If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state].
+
+<docs-warning>`unstable_viewTransition` only works when using a data router, see [Picking a Router][picking-a-router]</docs-warning>
+
+<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
+
 [link]: ../components/link
 [redirect]: ../fetch/redirect
 [loaders]: ../route/loader
 [actions]: ../route/action
 [history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
 [scrollrestoration]: ../components/scroll-restoration
+[use-view-transition-state]: ../hooks//use-view-transition-state
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+[picking-a-router]: ../routers/picking-a-router
diff --git a/docs/hooks/use-submit.md b/docs/hooks/use-submit.md
@@ -150,7 +150,7 @@ submit(null, {
 <Form action="/logout" method="post" />;
 ```
 
-Because submissions are navigations, the options may also contain the other navigation related props from [`<Form>`][form] such as `replace`, `state`, `preventScrollReset`, `relative`, etc.
+Because submissions are navigations, the options may also contain the other navigation related props from [`<Form>`][form] such as `replace`, `state`, `preventScrollReset`, `relative`, `unstable_viewTransition` etc.
 
 [pickingarouter]: ../routers/picking-a-router
 [form]: ../components/form
diff --git a/docs/hooks/use-view-transition-state.md b/docs/hooks/use-view-transition-state.md
@@ -0,0 +1,50 @@
+---
+title: unstable_useViewTransitionState
+---
+
+# `unstable_useViewTransitionState`
+
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function unstable_useViewTransitionState(
+  to: To,
+  opts: { relative?: "route" : "path" } = {}
+): boolean;
+
+type To = string | Partial<Path>;
+
+interface Path {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+```
+
+</details>
+
+This hook returns `true` when there is an active [View Transition][view-transitions] to the specified location. This can be used to apply finer-grained styles to elements to further customize the view transition. This requires that view transitions have been enabled for the given navigation via the [unstable_viewTransition][link-view-transition] prop on the `Link` (or the `Form`, `navigate`, or `submit` call).
+
+Consider clicking on an image in a list that you need to expand into the hero image on the destination page:
+
+```jsx
+function NavImage({ src, alt, id }) {
+  let to = `/images/${idx}`;
+  let vt = unstable_useViewTransitionState(href);
+  return (
+    <Link to={to} unstable_viewTransition>
+      <img
+        src={src}
+        alt={alt}
+        style={{
+          viewTransitionName: vt ? "image-expand" : "",
+        }}
+      />
+    </Link>
+  );
+}
+```
+
+[link-view-transition]: ../components/link#unstable_viewtransition
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
diff --git a/docs/routers/picking-a-router.md b/docs/routers/picking-a-router.md
@@ -109,6 +109,7 @@ The following APIs are introduced in React Router 6.4 and will only work when us
 - [`useRouteError`][userouteerror]
 - [`useRouteLoaderData`][userouteloaderdata]
 - [`useSubmit`][usesubmit]
+- `startViewTransition` support on [Link][viewtransition-link] and [useNavigate][viewtransition-navigate]
 
 [createbrowserrouter]: ./create-browser-router
 [createhashrouter]: ./create-hash-router
@@ -142,3 +143,5 @@ The following APIs are introduced in React Router 6.4 and will only work when us
 [userouteerror]: ../hooks/use-route-error
 [userouteloaderdata]: ../hooks/use-route-loader-data
 [usesubmit]: ../hooks/use-submit
+[viewtransition-link]: ../components/link#unstable_viewtransition
+[viewtransition-navigate]: ../hooks/use-navigate#optionsunstable_viewtransition
diff --git a/docs/routers/router-provider.md b/docs/routers/router-provider.md
@@ -16,7 +16,7 @@ declare function RouterProvider(
 interface RouterProviderProps {
   fallbackElement?: React.ReactNode;
   router: Router;
-  future?: FutureConfig;
+  future?: Partial<FutureConfig>;
 }
 ```
 

diff --git a/examples/view-transitions/.gitignore b/examples/view-transitions/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
diff --git a/examples/view-transitions/.stackblitzrc b/examples/view-transitions/.stackblitzrc
@@ -0,0 +1,4 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm run dev"
+}
diff --git a/examples/view-transitions/README.md b/examples/view-transitions/README.md
@@ -0,0 +1,14 @@
+---
+title: View Transitions
+toc: false
+---
+
+# startViewTransition (Experimental)
+
+This example demonstrates a simple usage of a Data Router with `document.startViewTransition` enabled.
+
+## Preview
+
+Open this example on [StackBlitz](https://stackblitz.com):
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/remix-run/react-router/tree/main/examples/view-transitions?file=src/App.tsx)