react-router 6.27.0 → 7.0.0-pre.1

package/dist/lib/hooks.d.ts

@@ -1,38 +1,62 @@
 import * as React from "react";
-import type { Blocker, BlockerFunction, Location, ParamParseKey, Params, Path, PathMatch, PathPattern, RelativeRoutingType, Router as RemixRouter, RevalidationState, To, UIMatch } from "@remix-run/router";
-import { Action as NavigationType } from "@remix-run/router";
 import type { NavigateOptions, RouteContextObject, RouteMatch, RouteObject } from "./context";
+import type { Location, Path, To } from "./router/history";
+import { Action as NavigationType } from "./router/history";
+import type { Blocker, BlockerFunction, RelativeRoutingType, Router as DataRouter, RevalidationState } from "./router/router";
+import type { ParamParseKey, Params, PathMatch, PathPattern, UIMatch } from "./router/utils";
 /**
- * Returns the full href for the given "to" value. This is useful for building
- * custom links that are also accessible and preserve right-click behavior.
- *
- * @see https://reactrouter.com/hooks/use-href
+  Resolves a URL against the current location.
+
+  ```tsx
+  import { useHref } from "react-router"
+
+  function SomeComponent() {
+    let href = useHref("some/where");
+    // "/resolved/some/where"
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useHref(to: To, { relative }?: {
     relative?: RelativeRoutingType;
 }): string;
 /**
- * Returns true if this component is a descendant of a `<Router>`.
+ * Returns true if this component is a descendant of a Router, useful to ensure
+ * a component is used within a Router.
  *
- * @see https://reactrouter.com/hooks/use-in-router-context
+ * @category Hooks
  */
 export declare function useInRouterContext(): boolean;
 /**
- * Returns the current location object, which represents the current URL in web
- * browsers.
- *
- * Note: If you're using this it may mean you're doing some of your own
- * "routing" in your app, and we'd like to know what your use case is. We may
- * be able to provide something higher-level to better suit your needs.
- *
- * @see https://reactrouter.com/hooks/use-location
+  Returns the current {@link Location}. This can be useful if you'd like to perform some side effect whenever it changes.
+
+  ```tsx
+  import * as React from 'react'
+  import { useLocation } from 'react-router'
+
+  function SomeComponent() {
+    let location = useLocation()
+
+    React.useEffect(() => {
+      // Google Analytics
+      ga('send', 'pageview')
+    }, [location]);
+
+    return (
+      // ...
+    );
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useLocation(): Location;
 /**
  * Returns the current navigation action which describes how the router came to
  * the current location, either by a pop, push, or replace on the history stack.
  *
- * @see https://reactrouter.com/hooks/use-navigation-type
+ * @category Hooks
  */
 export declare function useNavigationType(): NavigationType;
 /**
@@ -40,63 +64,130 @@ export declare function useNavigationType(): NavigationType;
  * This is useful for components that need to know "active" state, e.g.
  * `<NavLink>`.
  *
- * @see https://reactrouter.com/hooks/use-match
+ * @category Hooks
  */
 export declare function useMatch<ParamKey extends ParamParseKey<Path>, Path extends string>(pattern: PathPattern<Path> | Path): PathMatch<ParamKey> | null;
 /**
  * The interface for the navigate() function returned from useNavigate().
  */
 export interface NavigateFunction {
-    (to: To, options?: NavigateOptions): void;
-    (delta: number): void;
+    (to: To, options?: NavigateOptions): void | Promise<void>;
+    (delta: number): void | Promise<void>;
 }
 /**
- * Returns an imperative method for changing the location. Used by `<Link>`s, but
- * may also be used by other elements to change the location.
- *
- * @see https://reactrouter.com/hooks/use-navigate
+  Returns a function that lets you navigate programmatically in the browser in response to user interactions or effects.
+
+  ```tsx
+  import { useNavigate } from "react-router";
+
+  function SomeComponent() {
+    let navigate = useNavigate();
+    return (
+      <button
+        onClick={() => {
+          navigate(-1);
+        }}
+      />
+    );
+  }
+  ```
+
+  It's often better to use {@link redirect} in {@link ActionFunction | actions} and {@link LoaderFunction | loaders} than this hook.
+
+  @category Hooks
  */
 export declare function useNavigate(): NavigateFunction;
 /**
- * Returns the context (if provided) for the child route at this level of the route
- * hierarchy.
- * @see https://reactrouter.com/hooks/use-outlet-context
+ * Returns the parent route {@link OutletProps.context | `<Outlet context>`}.
+ *
+ * @category Hooks
  */
 export declare function useOutletContext<Context = unknown>(): Context;
 /**
  * Returns the element for the child route at this level of the route
  * hierarchy. Used internally by `<Outlet>` to render child routes.
  *
- * @see https://reactrouter.com/hooks/use-outlet
+ * @category Hooks
  */
 export declare function useOutlet(context?: unknown): React.ReactElement | null;
 /**
- * Returns an object of key/value pairs of the dynamic params from the current
- * URL that were matched by the route path.
- *
- * @see https://reactrouter.com/hooks/use-params
+  Returns an object of key/value pairs of the dynamic params from the current URL that were matched by the routes. Child routes inherit all params from their parent routes.
+
+  ```tsx
+  import { useParams } from "react-router"
+
+  function SomeComponent() {
+    let params = useParams()
+    params.postId
+  }
+  ```
+
+  Assuming a route pattern like `/posts/:postId` is matched by `/posts/123` then `params.postId` will be `"123"`.
+
+  @category Hooks
  */
 export declare function useParams<ParamsOrKey extends string | Record<string, string | undefined> = string>(): Readonly<[
     ParamsOrKey
 ] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>>;
 /**
- * Resolves the pathname of the given `to` value against the current location.
- *
- * @see https://reactrouter.com/hooks/use-resolved-path
+  Resolves the pathname of the given `to` value against the current location. Similar to {@link useHref}, but returns a {@link Path} instead of a string.
+
+  ```tsx
+  import { useResolvedPath } from "react-router"
+
+  function SomeComponent() {
+    // if the user is at /dashboard/profile
+    let path = useResolvedPath("../accounts")
+    path.pathname // "/dashboard/accounts"
+    path.search // ""
+    path.hash // ""
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useResolvedPath(to: To, { relative }?: {
     relative?: RelativeRoutingType;
 }): Path;
 /**
- * Returns the element of the route that matched the current location, prepared
- * with the correct context to render the remainder of the route tree. Route
- * elements in the tree must render an `<Outlet>` to render their child route's
- * element.
- *
- * @see https://reactrouter.com/hooks/use-routes
+  Hook version of {@link Routes | `<Routes>`} that uses objects instead of components. These objects have the same properties as the component props.
+
+  The return value of `useRoutes` is either a valid React element you can use to render the route tree, or `null` if nothing matched.
+
+  ```tsx
+  import * as React from "react";
+  import { useRoutes } from "react-router";
+
+  function App() {
+    let element = useRoutes([
+      {
+        path: "/",
+        element: <Dashboard />,
+        children: [
+          {
+            path: "messages",
+            element: <DashboardMessages />,
+          },
+          { path: "tasks", element: <DashboardTasks /> },
+        ],
+      },
+      { path: "team", element: <AboutPage /> },
+    ]);
+
+    return element;
+  }
+  ```
+
+ @category Hooks
  */
 export declare function useRoutes(routes: RouteObject[], locationArg?: Partial<Location> | string): React.ReactElement | null;
-export declare function useRoutesImpl(routes: RouteObject[], locationArg?: Partial<Location> | string, dataRouterState?: RemixRouter["state"], future?: RemixRouter["future"]): React.ReactElement | null;
+/**
+ * Internal implementation with accept optional param for RouterProvider usage
+ *
+ * @private
+ * @category Hooks
+ */
+export declare function useRoutesImpl(routes: RouteObject[], locationArg?: Partial<Location> | string, dataRouterState?: DataRouter["state"], future?: DataRouter["future"]): React.ReactElement | null;
 type RenderErrorBoundaryProps = React.PropsWithChildren<{
     location: Location;
     revalidation: RevalidationState;
@@ -122,53 +213,189 @@ export declare class RenderErrorBoundary extends React.Component<RenderErrorBoun
     componentDidCatch(error: any, errorInfo: any): void;
     render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
 }
-export declare function _renderMatches(matches: RouteMatch[] | null, parentMatches?: RouteMatch[], dataRouterState?: RemixRouter["state"] | null, future?: RemixRouter["future"] | null): React.ReactElement | null;
+export declare function _renderMatches(matches: RouteMatch[] | null, parentMatches?: RouteMatch[], dataRouterState?: DataRouter["state"] | null, future?: DataRouter["future"] | null): React.ReactElement | null;
 /**
  * Returns the ID for the nearest contextual route
  */
 export declare function useRouteId(): string;
 /**
- * Returns the current navigation, defaulting to an "idle" navigation when
- * no navigation is in progress
+  Returns the current navigation, defaulting to an "idle" navigation when no navigation is in progress. You can use this to render pending UI (like a global spinner) or read FormData from a form navigation.
+
+  ```tsx
+  import { useNavigation } from "react-router"
+
+  function SomeComponent() {
+    let navigation = useNavigation();
+    navigation.state
+    navigation.formData
+    // etc.
+  }
+  ```
+
+  @category Hooks
  */
-export declare function useNavigation(): import("@remix-run/router").Navigation;
+export declare function useNavigation(): import("./router/router").Navigation;
 /**
- * Returns a revalidate function for manually triggering revalidation, as well
- * as the current state of any manual revalidations
+  Revalidate the data on the page for reasons outside of normal data mutations like window focus or polling on an interval.
+
+  ```tsx
+  import { useRevalidator } from "react-router";
+
+  function WindowFocusRevalidator() {
+    const revalidator = useRevalidator();
+
+    useFakeWindowFocus(() => {
+      revalidator.revalidate();
+    });
+
+    return (
+      <div hidden={revalidator.state === "idle"}>
+        Revalidating...
+      </div>
+    );
+  }
+  ```
+
+  Note that page data is already revalidated automatically after actions. If you find yourself using this for normal CRUD operations on your data in response to user interactions, you're probably not taking advantage of the other APIs like {@link useFetcher}, {@link Form}, {@link useSubmit} that do this automatically.
+
+  @category Hooks
  */
 export declare function useRevalidator(): {
-    revalidate: () => void;
+    revalidate(): Promise<void>;
     state: RevalidationState;
 };
 /**
  * Returns the active route matches, useful for accessing loaderData for
  * parent/child routes or the route "handle" property
+ *
+ * @category Hooks
  */
 export declare function useMatches(): UIMatch[];
 /**
- * Returns the loader data for the nearest ancestor Route loader
+  Returns the data from the closest route {@link LoaderFunction | loader} or {@link ClientLoaderFunction | client loader}.
+
+  ```tsx
+  import { useLoaderData } from "react-router"
+
+  export async function loader() {
+    return await fakeDb.invoices.findAll();
+  }
+
+  export default function Invoices() {
+    let invoices = useLoaderData<typeof loader>();
+    // ...
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useLoaderData(): unknown;
 /**
- * Returns the loaderData for the given routeId
+  Returns the loader data for a given route by route ID.
+
+  ```tsx
+  import { useRouteLoaderData } from "react-router";
+
+  function SomeComponent() {
+    const { user } = useRouteLoaderData("root");
+  }
+  ```
+
+  Route IDs are created automatically. They are simply the path of the route file relative to the app folder without the extension.
+
+  | Route Filename             | Route ID             |
+  | -------------------------- | -------------------- |
+  | `app/root.tsx`             | `"root"`             |
+  | `app/routes/teams.tsx`     | `"routes/teams"`     |
+  | `app/whatever/teams.$id.tsx` | `"whatever/teams.$id"` |
+
+  If you created an ID manually, you can use that instead:
+
+  ```tsx
+  route("/", "containers/app.tsx", { id: "app" }})
+  ```
+
+  @category Hooks
  */
 export declare function useRouteLoaderData(routeId: string): unknown;
 /**
- * Returns the action data for the nearest ancestor Route action
+  Returns the action data from the most recent POST navigation form submission or `undefined` if there hasn't been one.
+
+  ```tsx
+  import { Form, useActionData } from "react-router"
+
+  export async function action({ request }) {
+    const body = await request.formData()
+    const name = body.get("visitorsName")
+    return { message: `Hello, ${name}` }
+  }
+
+  export default function Invoices() {
+    const data = useActionData()
+    return (
+      <Form method="post">
+        <input type="text" name="visitorsName" />
+        {data ? data.message : "Waiting..."}
+      </Form>
+    )
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useActionData(): unknown;
 /**
- * Returns the nearest ancestor Route error, which could be a loader/action
- * error or a render error.  This is intended to be called from your
- * ErrorBoundary/errorElement to display a proper error message.
+  Accesses the error thrown during an {@link ActionFunction | action}, {@link LoaderFunction | loader}, or component render to be used in a route module Error Boundary.
+
+  ```tsx
+  export function ErrorBoundary() {
+    const error = useRouteError();
+    return <div>{error.message}</div>;
+  }
+  ```
+
+  @category Hooks
  */
 export declare function useRouteError(): unknown;
 /**
- * Returns the happy-path data from the nearest ancestor `<Await />` value
+  Returns the resolved promise value from the closest {@link Await | `<Await>`}.
+
+  ```tsx
+  function SomeDescendant() {
+    const value = useAsyncValue();
+    // ...
+  }
+
+  // somewhere in your app
+  <Await resolve={somePromise}>
+    <SomeDescendant />
+  </Await>
+  ```
+
+  @category Hooks
  */
 export declare function useAsyncValue(): unknown;
 /**
- * Returns the error from the nearest ancestor `<Await />` value
+  Returns the rejection value from the closest {@link Await | `<Await>`}.
+
+  ```tsx
+  import { Await, useAsyncError } from "react-router"
+
+  function ErrorElement() {
+    const error = useAsyncError();
+    return (
+      <p>Uh Oh, something went wrong! {error.message}</p>
+    );
+  }
+
+  // somewhere in your app
+  <Await
+    resolve={promiseThatRejects}
+    errorElement={<ErrorElement />}
+  />
+  ```
+
+  @category Hooks
  */
 export declare function useAsyncError(): unknown;
 /**
@@ -176,6 +403,8 @@ export declare function useAsyncError(): unknown;
  * user a confirmation dialog to confirm the navigation.  Mostly used to avoid
  * using half-filled form data.  This does not handle hard-reloads or
  * cross-origin navigations.
+ *
+ * @category Hooks
  */
 export declare function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker;
 export {};