6.4 Docs Updates (#9151)

brophdawg11 · web-flow · commit 0546ba91813b · 2022-09-07T14:57:02.000-04:00
* docs: minor typing updates to align with docs * Add new indicator to fetch utils * Various other typo fixes and link fixes * fix up types for scroll restoration matches * Revert "docs: minor typing updates to align with docs" This reverts commit e1b52ed. * Revert "fix up types for scroll restoration matches" This reverts commit e714bd2. * Remove duped link * Remix -> React Router * Add docs for new 'relative=path' option
diff --git a/docs/components/form.md b/docs/components/form.md
@@ -187,6 +187,10 @@ We've found with `get` you often want the user to be able to click "back" to see
 
 In other words, this is really only useful for GET submissions and you want to avoid the back button showing the previous results.
 
+## `relative`
+
+By default, paths are relative to the route hierarchy, so `..` will go up one `Route` level. Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you're prefer to use relative _path_ routing. You can opt into this behavior with `<Form to="../some/where" relative="path">`
+
 ## `reloadDocument`
 
 Instructs the form to skip React Router and submit the form with the browser's built in behavior.
diff --git a/docs/components/link.md b/docs/components/link.md
@@ -4,7 +4,7 @@ title: Link
 
 # `<Link>`
 
-<docs-info>ZZZ This is the web version of `<Link>`. For the React Native version, [go here][link-native].</docs-info>
+<docs-info>This is the web version of `<Link>`. For the React Native version, [go here][link-native].</docs-info>
 
 <details>
   <summary>Type declaration</summary>
@@ -54,7 +54,30 @@ A relative `<Link to>` value (that does not begin with `/`) resolves relative to
 
 <docs-info>`<Link to>` with a `..` behaves differently from a normal `<a href>` when the current URL ends with `/`. `<Link to>` ignores the trailing slash, and removes one URL segment for each `..`. But an `<a href>` value handles `..` differently when the current URL ends with `/` vs when it does not.</docs-info>
 
-[link-native]: ./link-native
+## `relative`
+
+By default, links are relative to the route hierarchy, so `..` will go up one `Route` level. Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you're prefer to use relative _path_ routing. You can opt into this behavior with `relative`:
+
+```jsx
+// Contact and EditContact do not share additional UI layout
+<Route path="/" element={<Layout />}>
+  <Route path="contacts/:id" element={<Contact />} />
+  <Route
+    path="contacts/:id/edit"
+    element={<EditContact />}
+  />
+</Route>;
+
+function EditContact() {
+  // Since Contact is not a parent of EditContact we need to go up one level
+  // in the path, instead of one level in the Route hierarchy
+  return (
+    <Link to=".." relative="path">
+      Cancel
+    </Link>
+  );
+}
+```
 
 ## `preventScrollReset`
 
@@ -93,4 +116,5 @@ An example when you might want this behavior is a list of tabs that manipulate t
 
 ```
 
+[link-native]: ./link-native
 [scrollrestoration]: ./scroll-restoration
diff --git a/docs/components/navigate.md b/docs/components/navigate.md
@@ -14,6 +14,7 @@ interface NavigateProps {
   to: To;
   replace?: boolean;
   state?: any;
+  relative?: RelativeRoutingType;
 }
 ```
 
diff --git a/docs/getting-started/_data.md b/docs/getting-started/_data.md
@@ -15,15 +15,15 @@ React Router v6.4 introduces all of the data abstractions from [Remix][remix] fo
 
 ## Installation
 
-The new Data APIs are available on the `next` tag:
+The new Data APIs are available on the `pre` tag:
 
 ```sh
-npm install react-router-dom@next
+npm install react-router-dom@pre
 ```
 
 ## Configuring Routes
 
-Configuring routes is the same, except you need to use [`DataBrowserRouter`][databrowserrouter] to enable the data APIs. note you no longer render `<Routes>` either, just `<Route>`.
+Configuring routes is the same, except you need to use [`DataBrowserRouter`][databrowserrouter] to enable the data APIs. Note you no longer render `<Routes>` either, just `<Route>`.
 
 <docs-info>It's important to render `DataBrowserRouter` at the top of the React tree.</docs-info>
 
@@ -255,6 +255,7 @@ export default function Root() {
 With the route configured, we can create an [`action`][action]. Actions are like [loaders][loader] except instead "reading" data they "write" data. Think of it like `React.useState`. It returns a reader and a writer. In React Router, loaders are your readers, actions are your writers.
 
 ```jsx
+// Sample code - this does not actually work :)
 const [reader, writer] = React.useState();
 <Route loader={reader} action={writer} />;
 ```
@@ -283,7 +284,7 @@ export default function NewNote() {
 
 Now add it to the route config:
 
-```jsx filename=main.jsx lines=[3,13]
+```jsx filename=main.jsx lines=[4,13]
 // ...
 import Root, { loader as rootLoader } from "./routes/root";
 import NewNote, {
diff --git a/docs/hooks/use-async-error.md b/docs/hooks/use-async-error.md
@@ -10,7 +10,7 @@ Returns the rejection value from the nearest [`<Await>`][await] component.
 ```tsx [4,12]
 import { useAsyncError, Await } from "react-router-dom";
 
-function ErrorHandler() {
+function ErrorElement() {
   const error = useAsyncError();
   return (
     <p>Uh Oh, something went wrong! {error.message}</p>
diff --git a/docs/hooks/use-fetcher.md b/docs/hooks/use-fetcher.md
@@ -62,7 +62,7 @@ You can know the state of the fetcher with `fetcher.state`. It will be one of:
 
 - **idle** - nothing is being fetched.
 - **submitting** - A route action is being called due to a fetcher submission using POST, PUT, PATCH, or DELETE
-- **loading** - The fetcher is calling a loader (from a `fetcher.load`) or the route data on the page is being revalidated after a fetcher submission
+- **loading** - The fetcher is calling a loader (from a `fetcher.load`) or is being revalidated after a separate submission or `useRevalidator` call
 
 ## `fetcher.Form`
 
@@ -220,6 +220,6 @@ Tells you the method of the form being submitted: get, post, put, patch, or dele
 fetcher.formMethod; // "post"
 ```
 
-[indexsearchparam]: ../route/route
+[indexsearchparam]: ../guides/index-search-param
 [link]: ../components/link
 [form]: ../components/form
diff --git a/docs/hooks/use-form-action.md b/docs/hooks/use-form-action.md
@@ -5,7 +5,19 @@ new: true
 
 # `useFormAction`
 
-This hook is used internally in [Form] to automatically resolve default and relative actions to the current route in context. While uncommon, you can use it directly to do things like compute the correct action for a `<button formAction>` to change the action of the button's `<Form>`. <small>(Yes, HTML buttons can change the action of their form!)</small>
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function useFormAction(
+  action?: string,
+  { relative }: { relative?: RelativeRoutingType } = {}
+): string;
+```
+
+</details>
+
+This hook is used internally in [`<Form>`][form] to automatically resolve default and relative actions to the current route in context. While uncommon, you can use it directly to do things like compute the correct action for a `<button formAction>` to change the action of the button's `<Form>`. <small>(Yes, HTML buttons can change the action of their form!)</small>
 
 ```tsx
 import { useFormAction } from "react-router-dom";
@@ -26,9 +38,10 @@ It's also useful for automatically resolving the action for [`submit`][usesubmit
 
 ```tsx
 let submit = useSubmit();
-let action = useResolvedAction();
+let action = useFormAction();
 submit(formData, { action });
 ```
 
+[form]: ../components/form
 [usesubmit]: ./use-submit
 [usefetchersubmit]: ./use-fetcher#fetchersubmit
diff --git a/docs/hooks/use-href.md b/docs/hooks/use-href.md
@@ -8,7 +8,10 @@ title: useHref
   <summary>Type declaration</summary>
 
 ```tsx
-declare function useHref(to: To): string;
+declare function useHref(
+  to: To,
+  options?: { relative?: RelativeRoutingType }
+): string;
 ```
 
 </details>
diff --git a/docs/hooks/use-link-click-handler.md b/docs/hooks/use-link-click-handler.md
@@ -16,6 +16,7 @@ declare function useLinkClickHandler<
     target?: React.HTMLAttributeAnchorTarget;
     replace?: boolean;
     state?: any;
+    options?: { relative?: RelativeRoutingType };
   }
 ): (event: React.MouseEvent<E, MouseEvent>) => void;
 ```
diff --git a/docs/hooks/use-navigate.md b/docs/hooks/use-navigate.md
@@ -31,7 +31,11 @@ declare function useNavigate(): NavigateFunction;
 interface NavigateFunction {
   (
     to: To,
-    options?: { replace?: boolean; state?: any }
+    options?: {
+      replace?: boolean;
+      state?: any;
+      relative?: RelativeRoutingType;
+    }
   ): void;
   (delta: number): void;
 }
diff --git a/docs/hooks/use-resolved-path.md b/docs/hooks/use-resolved-path.md
@@ -8,7 +8,10 @@ title: useResolvedPath
   <summary>Type declaration</summary>
 
 ```tsx
-declare function useResolvedPath(to: To): Path;
+declare function useResolvedPath(
+  to: To,
+  options?: { relative?: RelativeRoutingType }
+): Path;
 ```
 
 </details>
diff --git a/docs/route/action.md b/docs/route/action.md
@@ -7,6 +7,8 @@ new: true
 
 Route actions are the "writes" to route [loader][loader] "reads". They provide a way for apps to perform data mutations with simple HTML and HTTP semantics while React Router abstracts away the complexity of asynchronous UI and revalidation. This gives you the simple mental model of HTML + HTTP (where the browser handles the asynchrony and revalidation) with the behavior and and UX capabilities of modern SPAs.
 
+<docs-error>This feature only works if using a data router</docs-error>
+
 ```tsx
 <Route
   path="/song/:songId/edit"
diff --git a/docs/route/error-element.md b/docs/route/error-element.md
@@ -7,6 +7,8 @@ new: true
 
 When exceptions are thrown in [loaders][loader], [actions][action], or component rendering, instead of the normal render path for your Routes (`<Route element>`), the error path will be rendered (`<Route errorElement>`) and the error made available with [`useRouteError`][userouteerror].
 
+<docs-error>This feature only works if using a data router</docs-error>
+
 ```tsx
 <Route
   path="/invoices/:id"
diff --git a/docs/route/loader.md b/docs/route/loader.md
@@ -127,7 +127,7 @@ You can construct the response yourself as well:
 />
 ```
 
-Remix will automatically call `response.json()` so your components don't need to parse it while rendering:
+React Router will automatically call `response.json()` so your components don't need to parse it while rendering:
 
 ```tsx
 function SomeRoute() {
diff --git a/docs/route/route.md b/docs/route/route.md
@@ -15,7 +15,7 @@ Routes are perhaps the most important part of a React Router app. They couple UR
     element={<Team />}
     // when the URL matches this segment
     path="teams/:teamId"
-    // with this data before rendering
+    // with this data loaded before rendering
     loader={async ({ params }) => {
       return fetch(`/fake/api/teams/${params.teamId}.json`);
     }}
@@ -59,10 +59,13 @@ interface RouteProps {
   index?: boolean;
   children?: React.ReactNode;
   caseSensitive?: boolean;
-  loader?: DataFunction;
-  action?: DataFunction;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
   element?: React.ReactNode | null;
-  errorElement?: React.Node | null;
+  errorElement?: React.ReactNode | null;
+  handle?: RouteObject["handle"];
+  shouldRevalidate?: ShouldRevalidateFunction;
 }
 ```
 
@@ -92,7 +95,7 @@ If a path segment starts with `:` then it becomes a "dynamic segment". When the
 // and the element through `useParams`
 function Team() {
   let params = useParams();
-  console.log(params.teamId); // "hotspurs"
+  console.log(params.teamId); // "hotspur"
 }
 ```
 
@@ -136,7 +139,7 @@ Also known as "catchall" and "star" segments. If a route path pattern ends with
   path="/files/*"
   // the matching param will be available to the loader
   loader={({ params }) => {
-    console.log(params["*"]); // "files/one/two"
+    console.log(params["*"]); // "one/two"
   }}
   // and the action
   action={({ params }) => {}}
@@ -146,7 +149,7 @@ Also known as "catchall" and "star" segments. If a route path pattern ends with
 // and the element through `useParams`
 function Team() {
   let params = useParams();
-  console.log(params["*"]); // "hotspurs"
+  console.log(params["*"]); // "one/two"
 }
 ```
 
@@ -250,7 +253,7 @@ When a route throws an exception while rendering, in a `loader` or in an `action
   // or this while loading properties
   loader={() => loadProperties()}
   // or this while creating a property
-  action={({ request }) =>
+  action={async ({ request }) =>
     createProperty(await request.formData())
   }
   // then this element will render
diff --git a/docs/routers/data-browser-router.md b/docs/routers/data-browser-router.md
@@ -38,6 +38,7 @@ declare function DataBrowserRouter(
 ): React.ReactElement;
 
 export interface DataBrowserRouterProps {
+  basename?: string;
   children?: React.ReactNode;
   hydrationData?: HydrationState;
   fallbackElement?: React.ReactNode;
@@ -94,7 +95,7 @@ Typically, SSR implementations will provide that data on `window`. The `hydratio
     // data for the loaders keyed by route ids
     loaderData: {
       "/": window._remix.routeData.root,
-      "/event/:id": window.routeData.event,
+      "/event/:id": window._remix.routeData.event,
     },
 
     // data for an action, same shape as loaderData or null
diff --git a/docs/routers/data-hash-router.md b/docs/routers/data-hash-router.md
@@ -35,6 +35,7 @@ declare function DataHashRouter(
 ): React.ReactElement;
 
 export interface DataHashRouterProps {
+  basename?: string;
   children?: React.ReactNode;
   hydrationData?: HydrationState;
   fallbackElement?: React.ReactNode;
diff --git a/docs/routers/data-memory-router.md b/docs/routers/data-memory-router.md
@@ -46,6 +46,7 @@ declare function DataMemoryRouter(
 ): React.ReactElement;
 
 export interface DataMemoryRouterProps {
+  basename?: string;
   children?: React.ReactNode;
   initialEntries?: InitialEntry[];
   initialIndex?: number;

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ interface NavigateProps {`
`14`	`14`	`to: To;`
`15`	`15`	`replace?: boolean;`
`16`	`16`	`state?: any;`
	`17`	`+ relative?: RelativeRoutingType;`
`17`	`18`	`}`
`18`	`19`	```
`19`	`20`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ declare function useLinkClickHandler<`
`16`	`16`	`target?: React.HTMLAttributeAnchorTarget;`
`17`	`17`	`replace?: boolean;`
`18`	`18`	`state?: any;`
	`19`	`+ options?: { relative?: RelativeRoutingType };`
`19`	`20`	`}`
`20`	`21`	`): (event: React.MouseEvent<E, MouseEvent>) => void;`
`21`	`22`	```
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,11 @@ declare function useNavigate(): NavigateFunction;`
`31`	`31`	`interface NavigateFunction {`
`32`	`32`	`(`
`33`	`33`	`to: To,`
`34`		`- options?: { replace?: boolean; state?: any }`
	`34`	`+ options?: {`
	`35`	`+ replace?: boolean;`
	`36`	`+ state?: any;`
	`37`	`+ relative?: RelativeRoutingType;`
	`38`	`+ }`
`35`	`39`	`): void;`
`36`	`40`	`(delta: number): void;`
`37`	`41`	`}`