feat(elements): Add <Link /> component (#4456)

Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com>

Author: alexcarpenter

.changeset/short-mails-brush.md

@@ -0,0 +1,20 @@
+---
+'@clerk/elements': patch
+---
+
+Add Elements `<Link />` component.
+
+```tsx
+import * as Clerk from '@clerk/elements/common';
+import NextLink from 'next/link';
+
+function SignInPage() {
+  return (
+    <>
+      <Clerk.Link navigate='sign-up'>Sign up</Clerk.Link>
+
+      <Clerk.Link navigate='sign-up'>{url => <NextLink href={url}>Sign up</NextLink>}</Clerk.Link>
+    </>
+  );
+}
+```

.changeset/weak-hornets-hunt.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Expose internal `__internal_getOption` method from Clerk.

packages/clerk-js/src/core/clerk.ts

@@ -252,6 +252,10 @@ export class Clerk implements ClerkInterface {
     return this.#options.standardBrowser || false;
   }
 
+  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
+    return this.#options[key];
+  }
+
   public constructor(key: string, options?: DomainOrProxyUrl) {
     key = (key || '').trim();
 

packages/elements/src/react/common/index.ts

@@ -4,6 +4,7 @@ import 'client-only';
 export { Field, FieldError, FieldState, GlobalError, Input, Label, Submit } from '~/react/common/form';
 export { Connection, Icon } from '~/react/common/connections';
 export { Loading } from '~/react/common/loading';
+export { Link } from '~/react/common/link';
 
 export type {
   FormFieldErrorProps,

packages/elements/src/react/common/link.tsx

@@ -0,0 +1,60 @@
+import { useClerk } from '@clerk/shared/react';
+import { useClerkRouter } from '@clerk/shared/router';
+import type { ClerkOptions } from '@clerk/types';
+import React from 'react';
+
+type Destination = 'sign-in' | 'sign-up';
+export interface LinkProps extends Omit<React.HTMLAttributes<HTMLAnchorElement>, 'children'> {
+  navigate: Destination;
+  children: React.ReactNode | ((props: { url: string }) => React.ReactNode);
+}
+
+const paths: Record<Destination, keyof Pick<ClerkOptions, 'signInUrl' | 'signUpUrl'>> = {
+  'sign-in': 'signInUrl',
+  'sign-up': 'signUpUrl',
+};
+
+/**
+ * The `<Link>` component is used to navigate between sign-in and sign-up flows.
+ *
+ * @param {Destination} navigate - The destination to navigate to.
+ *
+ * @example
+ * ```tsx
+ * <Link navigate="sign-in">Sign in</Link>
+ * ```
+ * @example
+ * ```tsx
+ * <Link navigate="sign-in">
+ *  {({ url }) => (
+ *    <NextLink href={url}>Sign in</NextLink>
+ *  )}
+ * </Link>
+ */
+
+export function Link({ navigate, children, ...rest }: LinkProps) {
+  const router = useClerkRouter();
+  const clerk = useClerk();
+  const destinationUrl = router.makeDestinationUrlWithPreservedQueryParameters(
+    clerk.__internal_getOption(paths[navigate])!,
+  );
+
+  if (typeof children === 'function') {
+    return children({ url: destinationUrl });
+  }
+
+  return (
+    <a
+      onClick={e => {
+        if (router) {
+          e.preventDefault();
+          router.push(destinationUrl);
+        }
+      }}
+      href={destinationUrl}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}

packages/react/src/isomorphicClerk.ts

@@ -11,6 +11,7 @@ import type {
   AuthenticateWithMetamaskParams,
   Clerk,
   ClerkAuthenticateWithWeb3Params,
+  ClerkOptions,
   ClientResource,
   CreateOrganizationParams,
   CreateOrganizationProps,
@@ -254,6 +255,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return this.#proxyUrl || '';
   }
 
+  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] | undefined {
+    return this.clerkjs?.__internal_getOption(key);
+  }
+
   constructor(options: IsomorphicClerkOptions) {
     const { Clerk = null, publishableKey } = options || {};
     this.#publishableKey = publishableKey;

packages/shared/src/router/router.ts

@@ -8,6 +8,7 @@ export const PRESERVED_QUERYSTRING_PARAMS = ['after_sign_in_url', 'after_sign_up
  * Internal Clerk router, used by Clerk components to interact with the host's router.
  */
 export type ClerkRouter = {
+  makeDestinationUrlWithPreservedQueryParameters: (path: string) => string;
   /**
    * The basePath the router is currently mounted on.
    */
@@ -132,6 +133,7 @@ export function createClerkRouter(router: ClerkHostRouter, basePath: string = '/
   }
 
   return {
+    makeDestinationUrlWithPreservedQueryParameters,
     child,
     match,
     mode: router.mode,

packages/types/src/clerk.ts

@@ -106,6 +106,8 @@ export interface Clerk {
    */
   loaded: boolean;
 
+  __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K];
+
   frontendApi: string;
 
   /** Clerk Publishable Key string. */