chore(clerk-react,types): Add JSDoc comments (#6669)

Author: dstaley

.changeset/ninety-crews-find.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -63,9 +63,12 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/create-organization-params.mdx",
   "types/element-object-key.mdx",
   "types/elements-config.mdx",
+  "types/errors.mdx",
   "types/experimental_checkout-button-props.mdx",
   "types/experimental_plan-details-button-props.mdx",
   "types/experimental_subscription-details-button-props.mdx",
+  "types/field-error.mdx",
+  "types/field-errors.mdx",
   "types/for-payer-type.mdx",
   "types/get-payment-attempts-params.mdx",
   "types/get-payment-sources-params.mdx",
@@ -119,9 +122,12 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/session-verification-types.mdx",
   "types/set-active-params.mdx",
   "types/set-active.mdx",
+  "types/sign-in-future-resource.mdx",
   "types/sign-in-resource.mdx",
+  "types/sign-in-signal-value.mdx",
   "types/sign-out.mdx",
   "types/sign-up-authenticate-with-metamask-params.mdx",
+  "types/sign-up-future-resource.mdx",
   "types/sign-up-resource.mdx",
   "types/signed-in-session-resource.mdx",
   "types/state-selectors.mdx",
@@ -203,19 +209,27 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "nextjs/current-user.mdx",
   "nextjs/get-auth.mdx",
   "clerk-react/api-keys.mdx",
+  "clerk-react/checkout-button-props.mdx",
+  "clerk-react/checkout-button.mdx",
   "clerk-react/clerk-provider-props.mdx",
+  "clerk-react/plan-details-button-props.mdx",
+  "clerk-react/plan-details-button.mdx",
   "clerk-react/protect.mdx",
   "clerk-react/redirect-to-create-organization.mdx",
   "clerk-react/redirect-to-organization-profile.mdx",
   "clerk-react/redirect-to-user-profile.mdx",
+  "clerk-react/subscription-details-button-props.mdx",
+  "clerk-react/subscription-details-button.mdx",
   "clerk-react/use-auth.mdx",
   "clerk-react/use-clerk.mdx",
   "clerk-react/use-organization-list.mdx",
   "clerk-react/use-organization.mdx",
   "clerk-react/use-reverification.mdx",
   "clerk-react/use-session-list.mdx",
   "clerk-react/use-session.mdx",
+  "clerk-react/use-sign-in-signal.mdx",
   "clerk-react/use-sign-in.mdx",
+  "clerk-react/use-sign-up-signal.mdx",
   "clerk-react/use-sign-up.mdx",
   "clerk-react/use-user.mdx",
   "backend/allowlist-identifier.mdx",

packages/react/src/hooks/useClerkSignal.ts

@@ -1,22 +1,12 @@
-import type { SignInSignal, SignUpSignal } from '@clerk/types';
+import type { SignInSignalValue, SignUpSignalValue } from '@clerk/types';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
 import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
 
-// These types are used to remove the `null` value from the underlying resource. This is safe because IsomorphicClerk
-// always returns a valid resource, even before Clerk is loaded, and if Clerk is loaded, the resource is guaranteed to
-// be non-null
-type NonNullSignInSignal = Omit<ReturnType<SignInSignal>, 'signIn'> & {
-  signIn: NonNullable<ReturnType<SignInSignal>['signIn']>;
-};
-type NonNullSignUpSignal = Omit<ReturnType<SignUpSignal>, 'signUp'> & {
-  signUp: NonNullable<ReturnType<SignUpSignal>['signUp']>;
-};
-
-function useClerkSignal(signal: 'signIn'): NonNullSignInSignal;
-function useClerkSignal(signal: 'signUp'): NonNullSignUpSignal;
-function useClerkSignal(signal: 'signIn' | 'signUp'): NonNullSignInSignal | NonNullSignUpSignal {
+function useClerkSignal(signal: 'signIn'): SignInSignalValue;
+function useClerkSignal(signal: 'signUp'): SignUpSignalValue;
+function useClerkSignal(signal: 'signIn' | 'signUp'): SignInSignalValue | SignUpSignalValue {
   useAssertWrappedByClerkProvider('useClerkSignal');
 
   const clerk = useIsomorphicClerkContext();
@@ -46,9 +36,9 @@ function useClerkSignal(signal: 'signIn' | 'signUp'): NonNullSignInSignal | NonN
   const getSnapshot = useCallback(() => {
     switch (signal) {
       case 'signIn':
-        return clerk.__internal_state.signInSignal() as NonNullSignInSignal;
+        return clerk.__internal_state.signInSignal() as SignInSignalValue;
       case 'signUp':
-        return clerk.__internal_state.signUpSignal() as NonNullSignUpSignal;
+        return clerk.__internal_state.signUpSignal() as SignUpSignalValue;
       default:
         throw new Error(`Unknown signal: ${signal}`);
     }
@@ -59,10 +49,34 @@ function useClerkSignal(signal: 'signIn' | 'signUp'): NonNullSignInSignal | NonN
   return value;
 }
 
+/**
+ * This hook allows you to access the Signal-based `SignIn` resource.
+ *
+ * @experimental This experimental API is subject to change.
+ * @example
+ * import { useSignInSignal } from "@clerk/clerk-react/experimental";
+ *
+ * function SignInForm() {
+ *   const { signIn, errors, fetchStatus } = useSignInSignal();
+ *   //
+ * }
+ */
 export function useSignInSignal() {
   return useClerkSignal('signIn');
 }
 
+/**
+ * This hook allows you to access the Signal-based `SignUp` resource.
+ *
+ * @experimental This experimental API is subject to change.
+ * @example
+ * import { useSignUpSignal } from "@clerk/clerk-react/experimental";
+ *
+ * function SignUpForm() {
+ *   const { signUp, errors, fetchStatus } = useSignUpSignal();
+ *   //
+ * }
+ */
 export function useSignUpSignal() {
   return useClerkSignal('signUp');
 }

packages/react/typedoc.json

@@ -1,4 +1,4 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/index.ts"]
+  "entryPoints": ["./src/index.ts", "./src/experimental.ts"]
 }

packages/types/src/signInFuture.ts

@@ -82,32 +82,123 @@ export interface SignInFutureFinalizeParams {
   navigate?: SetActiveNavigate;
 }
 
+/**
+ * The current active `SignIn` instance, for use in custom flows.
+ */
 export interface SignInFutureResource {
-  availableStrategies: SignInFirstFactor[];
-  status: SignInStatus | null;
-  isTransferable: boolean;
-  existingSession?: { sessionId: string };
+  /**
+   * The list of first-factor strategies that are available for the current sign-in attempt.
+   */
+  readonly availableStrategies: SignInFirstFactor[];
+
+  /**
+   * The status of the current sign-in attempt as a string (for example, `'needs_identifier'`, `'needs_first_factor'`,
+   * `'complete'`, etc.)
+   */
+  readonly status: SignInStatus | null;
+
+  /**
+   * Indicates that there is not a matching user for the first-factor verification used, and that the sign-in can be
+   * transferred to a sign-up.
+   */
+  readonly isTransferable: boolean;
+
+  readonly existingSession?: { sessionId: string };
+
+  /**
+   * Used to supply an identifier for the sign-in attempt. Calling this method will populate data on the sign-in
+   * attempt, such as `signIn.resource.supportedFirstFactors`.
+   */
   create: (params: SignInFutureCreateParams) => Promise<{ error: unknown }>;
+
+  /**
+   * Used to submit a password to sign-in.
+   */
   password: (params: SignInFuturePasswordParams) => Promise<{ error: unknown }>;
+
+  /**
+   *
+   */
   emailCode: {
+    /**
+     * Used to send an email code to sign-in
+     */
     sendCode: (params: SignInFutureEmailCodeSendParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a code sent via email to sign-in
+     */
     verifyCode: (params: SignInFutureEmailCodeVerifyParams) => Promise<{ error: unknown }>;
   };
+
+  /**
+   *
+   */
   phoneCode: {
+    /**
+     * Used to send a phone code to sign-in
+     */
     sendCode: (params: SignInFuturePhoneCodeSendParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a code sent via phone to sign-in
+     */
     verifyCode: (params: SignInFuturePhoneCodeVerifyParams) => Promise<{ error: unknown }>;
   };
+
+  /**
+   *
+   */
   resetPasswordEmailCode: {
+    /**
+     * Used to send a password reset code to the first email address on the account
+     */
     sendCode: () => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a password reset code sent via email. Will cause `signIn.status` to become `'needs_new_password'`.
+     */
     verifyCode: (params: SignInFutureEmailCodeVerifyParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to submit a new password, and move the `signIn.status` to `'complete'`.
+     */
     submitPassword: (params: SignInFutureResetPasswordSubmitParams) => Promise<{ error: unknown }>;
   };
+
+  /**
+   * Used to perform OAuth authentication.
+   */
   sso: (params: SignInFutureSSOParams) => Promise<{ error: unknown }>;
+
+  /**
+   *
+   */
   mfa: {
+    /**
+     * Used to send a phone code as a second factor to sign-in
+     */
     sendPhoneCode: () => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a phone code sent as a second factor to sign-in
+     */
     verifyPhoneCode: (params: SignInFutureMFAPhoneCodeVerifyParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a TOTP code as a second factor to sign-in
+     */
     verifyTOTP: (params: SignInFutureTOTPVerifyParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a backup code as a second factor to sign-in
+     */
     verifyBackupCode: (params: SignInFutureBackupCodeVerifyParams) => Promise<{ error: unknown }>;
   };
+
+  /**
+   * Used to convert a sign-in with `status === ‘complete’` into an active session. Will cause anything observing the
+   * session state (such as the `useUser()` hook) to update automatically.
+   */
   finalize: (params?: SignInFutureFinalizeParams) => Promise<{ error: unknown }>;
 }

packages/types/src/signUpFuture.ts

@@ -47,19 +47,68 @@ export interface SignUpFutureFinalizeParams {
   navigate?: SetActiveNavigate;
 }
 
+/**
+ * The current active `SignUp` instance, for use in custom flows.
+ */
 export interface SignUpFutureResource {
-  status: SignUpStatus | null;
-  unverifiedFields: SignUpIdentificationField[];
-  isTransferable: boolean;
-  existingSession?: { sessionId: string };
+  /**
+   * The status of the current sign-up attempt as a string (for example, `'missing_requirements'`, `'complete'`, `'abandoned'`, etc.)
+   */
+  readonly status: SignUpStatus | null;
+
+  /**
+   * An array of strings representing unverified fields such as `’email_address’`. Can be used to detect when verification is necessary.
+   */
+  readonly unverifiedFields: SignUpIdentificationField[];
+
+  /**
+   * Indicates that there is a matching user for provided identifier, and that the sign-up can be transferred to
+   * a sign-in.
+   */
+  readonly isTransferable: boolean;
+
+  readonly existingSession?: { sessionId: string };
+
   create: (params: SignUpFutureCreateParams) => Promise<{ error: unknown }>;
+
+  /**
+   *
+   */
   verifications: {
+    /**
+     * Used to send an email code to verify an email address.
+     */
     sendEmailCode: () => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a code sent via email.
+     */
     verifyEmailCode: (params: SignUpFutureEmailCodeVerifyParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to send a phone code to verify a phone number.
+     */
     sendPhoneCode: (params: SignUpFuturePhoneCodeSendParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Used to verify a code sent via phone.
+     */
     verifyPhoneCode: (params: SignUpFuturePhoneCodeVerifyParams) => Promise<{ error: unknown }>;
   };
+
+  /**
+   * Used to sign up using an email address and password.
+   */
   password: (params: SignUpFuturePasswordParams) => Promise<{ error: unknown }>;
+
+  /**
+   * Used to create an account using an OAuth connection.
+   */
   sso: (params: SignUpFutureSSOParams) => Promise<{ error: unknown }>;
+
+  /**
+   * Used to convert a sign-up with `status === ‘complete’` into an active session. Will cause anything observing the
+   * session state (such as the `useUser()` hook) to update automatically.
+   */
   finalize: (params?: SignUpFutureFinalizeParams) => Promise<{ error: unknown }>;
 }