docs(api/hooks): auto-generate docs for DOM-related hooks

.eslintrc

@@ -31,7 +31,7 @@
         "jsdoc/check-tag-names": [
           "error",
           {
-            "definedTags": ["additionalExamples", "category", "mode"]
+            "definedTags": ["additionalExamples", "category", "mode", "unstable"]
           }
         ],
         "jsdoc/no-defaults": "error",
@@ -63,7 +63,8 @@
                   "category",
                   "mode",
                   "param",
-                  "returns"
+                  "returns",
+                  "unstable"
                 ]
               }
             ]

docs/api/hooks/useBeforeUnload.md

@@ -4,30 +4,40 @@ title: useBeforeUnload
 
 # useBeforeUnload
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data, declarative]
 
 ## Summary
 
 [Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useBeforeUnload.html)
 
-Setup a callback to be fired on the window's `beforeunload` event.
+Set up a callback to be fired on [Window's `beforeunload` event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).
 
 ## Signature
 
 ```tsx
-useBeforeUnload(callback, options): void
+useBeforeUnload(callback: (event: BeforeUnloadEvent) => any, options?: {
+    capture?: boolean;
+}): void
 ```
 
 ## Params
 
 ### callback
 
-[modes: framework, data, declarative]
-
-_No documentation_
+The callback to be called when the `beforeunload` event is fired. This callback receives the `BeforeUnloadEvent` as its argument.
 
-### options
+### options.capture
 
-[modes: framework, data, declarative]
+If `true`, the event will be captured during the capture phase. Defaults to `false`.
 
-_No documentation_

docs/api/hooks/useFetcher.md

@@ -4,6 +4,17 @@ title: useFetcher
 
 # useFetcher
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data]
 
 ## Summary
@@ -12,7 +23,7 @@ title: useFetcher
 
 Useful for creating complex, dynamic user interfaces that require multiple, concurrent data interactions without causing a navigation.
 
-Fetchers track their own, independent state and can be used to load data, submit forms, and generally interact with loaders and actions.
+Fetchers track their own, independent state and can be used to load data, submit forms, and generally interact with [`action`](../../start/framework/route-module#action)s and [`loader`](../../start/framework/route-module#loader)s and actions.
 
 ```tsx
 import { useFetcher } from "react-router"
@@ -42,13 +53,12 @@ function SomeComponent() {
 ## Signature
 
 ```tsx
-useFetcher(options): FetcherWithComponents
+useFetcher<T = any>({ key, }: {})
 ```
 
 ## Params
 
-### options
+### options.key
 
-[modes: framework, data]
+A unique key to identify the fetcher. If not provided, a unique key will be generated for the fetcher.
 
-_No documentation_

docs/api/hooks/useFetchers.md

@@ -4,13 +4,24 @@ title: useFetchers
 
 # useFetchers
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data]
 
 ## Summary
 
 [Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useFetchers.html)
 
-Returns an array of all in-flight fetchers. This is useful for components throughout the app that didn't create the fetchers but want to use their submissions to participate in optimistic UI.
+Returns an array of all in-flight [`Fetcher`](https://api.reactrouter.com/v7/types/react_router.Fetcher.html)s. This is useful for components throughout the app that didn't create the fetchers but want to use their submissions to participate in optimistic UI.
 
 ```tsx
 import { useFetchers } from "react-router";
@@ -26,5 +37,8 @@ function SomeComponent() {
 ## Signature
 
 ```tsx
-useFetchers(): undefined
+useFetchers(): (Fetcher & {
+    key: string;
+})[]
 ```
+

docs/api/hooks/useFormAction.md

@@ -4,6 +4,17 @@ title: useFormAction
 
 # useFormAction
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data]
 
 ## Summary
@@ -12,7 +23,7 @@ title: useFormAction
 
 Resolves the URL to the closest route in the component hierarchy instead of the current URL of the app.
 
-This is used internally by [Form](../components/Form) resolve the action to the closest route, but can be used generically as well.
+This is used internally by [`Form`](../components/Form) resolve the `action` to the closest route, but can be used generically as well.
 
 ```tsx
 import { useFormAction } from "react-router";
@@ -29,19 +40,16 @@ function SomeComponent() {
 ## Signature
 
 ```tsx
-useFormAction(action, __namedParameters): string
+useFormAction()
 ```
 
 ## Params
 
 ### action
 
-[modes: framework, data]
-
-The action to append to the closest route URL.
+The action to append to the closest route URL. If not provided, defaults to the closest route URL.
 
-### \_\_namedParameters
+### options.relative
 
-[modes: framework, data]
+The relative routing type to use when resolving the action. Defaults to `"route"`.
 
-_No documentation_

docs/api/hooks/useLinkClickHandler.md

@@ -4,35 +4,67 @@ title: useLinkClickHandler
 
 # useLinkClickHandler
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data, declarative]
 
 ## Summary
 
 [Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useLinkClickHandler.html)
 
-Handles the click behavior for router `<Link>` components. This is useful if
-you need to create custom `<Link>` components with the same click behavior we
-use in our exported `<Link>`.
-
-
+Handles the click behavior for router [`Link`](../components/Link) components. This is useful if
+you need to create custom [`Link`](../components/Link) components with the same click behavior we
+use in our exported [`Link`](../components/Link).
 
 ## Signature
 
 ```tsx
-useLinkClickHandler(to, __namedParameters): undefined
+useLinkClickHandler<E extends Element = HTMLAnchorElement>(to: To, { target, replace: replaceProp, state, preventScrollReset, relative, viewTransition, }: {
+    target?: React.HTMLAttributeAnchorTarget;
+    replace?: boolean;
+    state?: any;
+    preventScrollReset?: boolean;
+    relative?: RelativeRoutingType;
+    viewTransition?: boolean;
+} = {}): (event: React.MouseEvent<E, MouseEvent>) => void
 ```
 
 ## Params
 
 ### to
 
-[modes: framework, data, declarative]
+The URL to navigate to, can be a string or a partial [`Path`](https://api.reactrouter.com/v7/interfaces/react_router.Path.html).
+
+### options.preventScrollReset
+
+Whether to prevent the scroll position from being reset to the top of the viewport on completion of the navigation when using the [`ScrollRestoration`](../components/ScrollRestoration) component, defaults to `false`.
+
+### options.relative
+
+The relative routing type to use for the link, defaults to `"route"`. See [`RelativeRoutingType`](https://api.reactrouter.com/v7/types/react_router.RelativeRoutingType.html) for more details.
+
+### options.replace
+
+Whether to replace the current history entry instead of pushing a new one, defaults to `false`.
+
+### options.state
+
+The state to add to the history entry for this navigation, defaults to `undefined`.
 
-_No documentation_
+### options.target
 
-### __namedParameters
+The target attribute for the link, defaults to `_self`.
 
-[modes: framework, data, declarative]
+### options.viewTransition
 
-_No documentation_
+Enables a [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for this navigation, defaults to `false`. To apply specific styles during the transition see [`useViewTransitionState`](../hooks/useViewTransitionState).
 

docs/api/hooks/usePrompt.md

@@ -5,13 +5,24 @@ unstable: true
 
 # unstable_usePrompt
 
+<!--
+⚠️ ⚠️ IMPORTANT ⚠️ ⚠️ 
+
+Hey! Thank you for helping improve our documentation!
+
+This file is auto-generated from the JSDoc comments in the source
+code, so please find the definition of this API and edit the JSDoc
+comments accordingly and this file will be re-generated once those
+changes are merged.
+-->
+
 [MODES: framework, data]
 
 ## Summary
 
 [Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.unstable_usePrompt.html)
 
-Wrapper around useBlocker to show a window.confirm prompt to users instead of building a custom UI with [useBlocker](../hooks/useBlocker).
+Wrapper around [`useBlocker`](../hooks/useBlocker) to show a [`window.confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm) prompt to users instead of building a custom UI with [`useBlocker`](../hooks/useBlocker).
 
 The `unstable_` flag will not be removed because this technique has a lot of rough edges and behaves very differently (and incorrectly sometimes) across browsers if users click addition back/forward navigations while the confirmation is open. Use at your own risk.
 
@@ -46,11 +57,19 @@ function ImportantForm() {
 ## Signature
 
 ```tsx
-unstable_usePrompt(options): void
+unstable_usePrompt({ when, message, }: {
+    when: boolean | BlockerFunction;
+    message: string;
+}): void
 ```
 
 ## Params
 
-### options
+### options.message
+
+The message to show in the confirmation dialog.
+
+### options.when
+
+A boolean or a function that returns a boolean indicating whether to block the navigation. If a function is provided, it will receive an object with `currentLocation` and `nextLocation` properties.
 
-_No documentation_