From 6b7e0c026052729a64db1f1e1c4b3162dffb5a9c Mon Sep 17 00:00:00 2001 From: Henrik Wenz Date: Fri, 23 Sep 2022 19:39:39 +0200 Subject: [PATCH 1/7] docs: Add inline documentation for Link props --- packages/next/client/link.tsx | 46 +++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index aa7670d53ca0b..440c765b89554 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -27,14 +27,60 @@ type OptionalKeys = { }[keyof T] type InternalLinkProps = { + /** + * The path or URL to navigate to. It can also be an object. + * + * @example https://nextjs.org/docs/api-reference/next/link#with-url-object + */ href: Url + /** + * Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes). + * + * @deprecated + */ as?: Url + /** + * Replace the current `history` state instead of adding a new url into the stack. + * + * @defaultValue `false` + */ replace?: boolean + /** + * Replace the current `history` state instead of adding a new url into the stack. + * + * @defaultValue `false` + */ scroll?: boolean + /** + * Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) or [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md). + * + * @defaultValue `false` + */ shallow?: boolean + /** + * Forces `Link` to send the `href` property to its child. + * + * @defaultValue `false` + */ passHref?: boolean + /** + * Prefetch the page in the background. + * Any `` that is in the viewport (initially or through scroll) will be preloaded. + * Prefetch can be disabled by passing `prefetch={false}`. When `prefetch` is set to `false`, prefetching will still occur on hover. Pages using [Static Generation](/docs/basic-features/data-fetching/get-static-props.md) will preload `JSON` files with the data for faster page transitions. Prefetching is only enabled in production. + * + * @defaultValue `true` + */ prefetch?: boolean + /** + * The active locale is automatically prepended. `locale` allows for providing a different locale. + * When `false` `href` has to include the locale as the default behavior is disabled. + */ locale?: string | false + /** + * Enable legacy link behaviour. + * @defaultValue `true` + * @see https://github.com/vercel/next.js/commit/489e65ed98544e69b0afd7e0cfc3f9f6c2b803b7 + */ legacyBehavior?: boolean // e: any because as it would otherwise overlap with existing types /** From 025b747322f7d0441e4c0f436cb8a3c9395b8cd0 Mon Sep 17 00:00:00 2001 From: Henrik Wenz Date: Fri, 23 Sep 2022 23:48:27 +0200 Subject: [PATCH 2/7] Unmark as props --- packages/next/client/link.tsx | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index 440c765b89554..a1167f4879f0c 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -35,8 +35,6 @@ type InternalLinkProps = { href: Url /** * Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes). - * - * @deprecated */ as?: Url /** From d0d6a9bd93acb4390b1ce817e3f03b196669ed8d Mon Sep 17 00:00:00 2001 From: Henrik Wenz Date: Sat, 24 Sep 2022 16:33:41 +0200 Subject: [PATCH 3/7] Document Link component --- packages/next/client/link.tsx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index a1167f4879f0c..beff9e50f3bca 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -197,6 +197,9 @@ type LinkPropsReal = React.PropsWithChildren< LinkProps > +/** + * React Component that enables client-side page transitions between routes. + */ const Link = React.forwardRef( function LinkComponent(props, forwardedRef) { if (process.env.NODE_ENV !== 'production') { From c94ca2712fc7b4a9a9173cc0589e2c20db3d1edc Mon Sep 17 00:00:00 2001 From: Henrik Wenz Date: Tue, 27 Sep 2022 08:56:19 +0200 Subject: [PATCH 4/7] Update packages/next/client/link.tsx Co-authored-by: JJ Kasper --- packages/next/client/link.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index beff9e50f3bca..bde6ed010fac9 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -46,7 +46,7 @@ type InternalLinkProps = { /** * Replace the current `history` state instead of adding a new url into the stack. * - * @defaultValue `false` + * @defaultValue `true` */ scroll?: boolean /** From 64cf0c64401668570c7b23cd347671110e15a82b Mon Sep 17 00:00:00 2001 From: Henrik Wenz Date: Tue, 27 Sep 2022 08:56:29 +0200 Subject: [PATCH 5/7] Update packages/next/client/link.tsx Co-authored-by: JJ Kasper --- packages/next/client/link.tsx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index bde6ed010fac9..fcd301f144057 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -44,7 +44,9 @@ type InternalLinkProps = { */ replace?: boolean /** - * Replace the current `history` state instead of adding a new url into the stack. + * Whether to override the default scroll behavior + * + * @example https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page * * @defaultValue `true` */ From d70ea52d53ce7ea8329ab3925d12ae5a39becf74 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 27 Sep 2022 11:07:09 -0700 Subject: [PATCH 6/7] lint fix --- packages/next/client/link.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index fcd301f144057..84d695f0887a0 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -45,7 +45,7 @@ type InternalLinkProps = { replace?: boolean /** * Whether to override the default scroll behavior - * + * * @example https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page * * @defaultValue `true` From cd23a129e1fd4ba6572c5fd629f000d5f660b8b6 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 27 Sep 2022 11:15:25 -0700 Subject: [PATCH 7/7] Apply suggestions from code review --- packages/next/client/link.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx index 84d695f0887a0..874aea5f74260 100644 --- a/packages/next/client/link.tsx +++ b/packages/next/client/link.tsx @@ -200,7 +200,7 @@ type LinkPropsReal = React.PropsWithChildren< > /** - * React Component that enables client-side page transitions between routes. + * React Component that enables client-side transitions between routes. */ const Link = React.forwardRef( function LinkComponent(props, forwardedRef) {