chore: Add react jsdocs

Author: Ehesp

packages/react/src/auth/forms/email-link-auth-form.tsx

@@ -28,11 +28,19 @@ import { form } from "~/components/form";
 import { Policies } from "~/components/policies";
 import { useCallback, useEffect, useState } from "react";
 
+/** Props for the EmailLinkAuthForm component. */
 export type EmailLinkAuthFormProps = {
+  /** Callback function called when the sign-in link email is sent. */
   onEmailSent?: () => void;
+  /** Callback function called when sign-in is completed via the email link. */
   onSignIn?: (credential: UserCredential) => void;
 };
 
+/**
+ * Creates a memoized action function for sending a sign-in link to an email address.
+ *
+ * @returns A callback function that sends a sign-in link to the specified email address.
+ */
 export function useEmailLinkAuthFormAction() {
   const ui = useUI();
 
@@ -53,6 +61,12 @@ export function useEmailLinkAuthFormAction() {
   );
 }
 
+/**
+ * Creates a form hook for email link authentication.
+ *
+ * @param onSuccess - Optional callback function called when the sign-in link email is sent.
+ * @returns A form instance configured for email link authentication.
+ */
 export function useEmailLinkAuthForm(onSuccess?: EmailLinkAuthFormProps["onEmailSent"]) {
   const schema = useEmailLinkAuthFormSchema();
   const action = useEmailLinkAuthFormAction();
@@ -75,6 +89,13 @@ export function useEmailLinkAuthForm(onSuccess?: EmailLinkAuthFormProps["onEmail
   });
 }
 
+/**
+ * Hook that automatically completes the email link sign-in process when the component mounts.
+ *
+ * Checks if the current URL contains a valid email link sign-in link and completes the authentication.
+ *
+ * @param onSignIn - Optional callback function called when sign-in is completed.
+ */
 export function useEmailLinkAuthFormCompleteSignIn(onSignIn?: EmailLinkAuthFormProps["onSignIn"]) {
   const ui = useUI();
 
@@ -91,6 +112,14 @@ export function useEmailLinkAuthFormCompleteSignIn(onSignIn?: EmailLinkAuthFormP
   }, [onSignIn]);
 }
 
+/**
+ * A form component for email link authentication.
+ *
+ * Sends a sign-in link to the user's email address and automatically completes sign-in
+ * if the user arrives via an email link.
+ *
+ * @returns The email link auth form component.
+ */
 export function EmailLinkAuthForm({ onEmailSent, onSignIn }: EmailLinkAuthFormProps) {
   const ui = useUI();
   const [emailSent, setEmailSent] = useState(false);

packages/react/src/auth/forms/forgot-password-auth-form.tsx

@@ -22,11 +22,19 @@ import { form } from "~/components/form";
 import { Policies } from "~/components/policies";
 import { useCallback, useState } from "react";
 
+/** Props for the ForgotPasswordAuthForm component. */
 export type ForgotPasswordAuthFormProps = {
+  /** Callback function called when the password reset email is sent. */
   onPasswordSent?: () => void;
+  /** Callback function called when the back to sign in link is clicked. */
   onBackToSignInClick?: () => void;
 };
 
+/**
+ * Creates a memoized action function for sending a password reset email.
+ *
+ * @returns A callback function that sends a password reset email to the specified address.
+ */
 export function useForgotPasswordAuthFormAction() {
   const ui = useUI();
 
@@ -47,6 +55,12 @@ export function useForgotPasswordAuthFormAction() {
   );
 }
 
+/**
+ * Creates a form hook for forgot password authentication.
+ *
+ * @param onSuccess - Optional callback function called when the password reset email is sent.
+ * @returns A form instance configured for forgot password.
+ */
 export function useForgotPasswordAuthForm(onSuccess?: ForgotPasswordAuthFormProps["onPasswordSent"]) {
   const schema = useForgotPasswordAuthFormSchema();
   const action = useForgotPasswordAuthFormAction();
@@ -69,6 +83,13 @@ export function useForgotPasswordAuthForm(onSuccess?: ForgotPasswordAuthFormProp
   });
 }
 
+/**
+ * A form component for requesting a password reset email.
+ *
+ * Displays a success message after the email is sent.
+ *
+ * @returns The forgot password form component.
+ */
 export function ForgotPasswordAuthForm({ onBackToSignInClick, onPasswordSent }: ForgotPasswordAuthFormProps) {
   const ui = useUI();
   const [emailSent, setEmailSent] = useState(false);

packages/react/src/auth/forms/mfa/sms-multi-factor-assertion-form.tsx

@@ -36,6 +36,11 @@ type PhoneMultiFactorInfo = MultiFactorInfo & {
   phoneNumber?: string;
 };
 
+/**
+ * Creates a memoized action function for verifying a phone number during SMS multi-factor assertion.
+ *
+ * @returns A callback function that verifies a phone number using the provided hint and reCAPTCHA verifier.
+ */
 export function useSmsMultiFactorAssertionPhoneFormAction() {
   const ui = useUI();
 
@@ -47,12 +52,22 @@ export function useSmsMultiFactorAssertionPhoneFormAction() {
   );
 }
 
+/** Options for the SMS multi-factor assertion phone form hook. */
 type UseSmsMultiFactorAssertionPhoneForm = {
+  /** The multi-factor info hint containing phone number information. */
   hint: MultiFactorInfo;
+  /** The reCAPTCHA verifier instance. */
   recaptchaVerifier: RecaptchaVerifier;
+  /** Callback function called when phone verification is successful. */
   onSuccess: (verificationId: string) => void;
 };
 
+/**
+ * Creates a form hook for SMS multi-factor assertion phone number verification.
+ *
+ * @param options - The phone form options.
+ * @returns A form instance configured for phone number verification.
+ */
 export function useSmsMultiFactorAssertionPhoneForm({
   hint,
   recaptchaVerifier,
@@ -120,6 +135,11 @@ function SmsMultiFactorAssertionPhoneForm(props: SmsMultiFactorAssertionPhoneFor
   );
 }
 
+/**
+ * Creates a memoized action function for verifying the SMS verification code during multi-factor assertion.
+ *
+ * @returns A callback function that verifies the code and signs in with the multi-factor assertion.
+ */
 export function useSmsMultiFactorAssertionVerifyFormAction() {
   const ui = useUI();
 
@@ -133,11 +153,20 @@ export function useSmsMultiFactorAssertionVerifyFormAction() {
   );
 }
 
+/** Options for the SMS multi-factor assertion verify form hook. */
 type UseSmsMultiFactorAssertionVerifyForm = {
+  /** The verification ID from the phone verification step. */
   verificationId: string;
+  /** Callback function called when verification is successful. */
   onSuccess: (credential: UserCredential) => void;
 };
 
+/**
+ * Creates a form hook for SMS multi-factor assertion verification code input.
+ *
+ * @param options - The verify form options.
+ * @returns A form instance configured for verification code input.
+ */
 export function useSmsMultiFactorAssertionVerifyForm({
   verificationId,
   onSuccess,
@@ -206,11 +235,21 @@ function SmsMultiFactorAssertionVerifyForm(props: SmsMultiFactorAssertionVerifyF
   );
 }
 
+/** Props for the SmsMultiFactorAssertionForm component. */
 export type SmsMultiFactorAssertionFormProps = {
+  /** The multi-factor info hint containing phone number information. */
   hint: MultiFactorInfo;
+  /** Optional callback function called when multi-factor assertion is successful. */
   onSuccess?: (credential: UserCredential) => void;
 };
 
+/**
+ * A form component for SMS multi-factor authentication assertion.
+ *
+ * Handles the two-step process: first verifying the phone number, then verifying the SMS code.
+ *
+ * @returns The SMS multi-factor assertion form component.
+ */
 export function SmsMultiFactorAssertionForm(props: SmsMultiFactorAssertionFormProps) {
   const [verification, setVerification] = useState<{
     verificationId: string;

packages/react/src/auth/forms/mfa/sms-multi-factor-enrollment-form.tsx

@@ -32,6 +32,11 @@ import {
   useUI,
 } from "~/hooks";
 
+/**
+ * Creates a memoized action function for verifying a phone number during SMS multi-factor enrollment.
+ *
+ * @returns A callback function that verifies a phone number for MFA enrollment using the provided reCAPTCHA verifier.
+ */
 export function useSmsMultiFactorEnrollmentPhoneAuthFormAction() {
   const ui = useUI();
 
@@ -44,12 +49,22 @@ export function useSmsMultiFactorEnrollmentPhoneAuthFormAction() {
   );
 }
 
+/** Options for the SMS multi-factor enrollment phone number form hook. */
 export type UseSmsMultiFactorEnrollmentPhoneNumberForm = {
+  /** The reCAPTCHA verifier instance. */
   recaptchaVerifier: RecaptchaVerifier;
+  /** Callback function called when phone verification is successful. */
   onSuccess: (verificationId: string, displayName?: string) => void;
+  /** Optional function to format the phone number before verification. */
   formatPhoneNumber?: (phoneNumber: string) => string;
 };
 
+/**
+ * Creates a form hook for SMS multi-factor enrollment phone number verification.
+ *
+ * @param options - The phone number form options.
+ * @returns A form instance configured for phone number input and verification for MFA enrollment.
+ */
 export function useSmsMultiFactorEnrollmentPhoneNumberForm({
   recaptchaVerifier,
   onSuccess,
@@ -131,6 +146,11 @@ function MultiFactorEnrollmentPhoneNumberForm(props: MultiFactorEnrollmentPhoneN
   );
 }
 
+/**
+ * Creates a memoized action function for verifying the SMS verification code during multi-factor enrollment.
+ *
+ * @returns A callback function that verifies the code and enrolls the phone number as a multi-factor authentication method.
+ */
 export function useMultiFactorEnrollmentVerifyPhoneNumberFormAction() {
   const ui = useUI();
   return useCallback(
@@ -151,12 +171,22 @@ export function useMultiFactorEnrollmentVerifyPhoneNumberFormAction() {
   );
 }
 
+/** Options for the multi-factor enrollment verify phone number form hook. */
 type UseMultiFactorEnrollmentVerifyPhoneNumberForm = {
+  /** The verification ID from the phone verification step. */
   verificationId: string;
+  /** Optional display name for the enrolled MFA method. */
   displayName?: string;
+  /** Callback function called when enrollment is successful. */
   onSuccess: () => void;
 };
 
+/**
+ * Creates a form hook for SMS multi-factor enrollment verification code input.
+ *
+ * @param options - The verify phone number form options.
+ * @returns A form instance configured for verification code input during MFA enrollment.
+ */
 export function useMultiFactorEnrollmentVerifyPhoneNumberForm({
   verificationId,
   displayName,
@@ -184,12 +214,21 @@ export function useMultiFactorEnrollmentVerifyPhoneNumberForm({
   });
 }
 
+/** Props for the MultiFactorEnrollmentVerifyPhoneNumberForm component. */
 type MultiFactorEnrollmentVerifyPhoneNumberFormProps = {
+  /** The verification ID from the phone verification step. */
   verificationId: string;
+  /** Optional display name for the enrolled MFA method. */
   displayName?: string;
+  /** Callback function called when enrollment is successful. */
   onSuccess: () => void;
 };
 
+/**
+ * A form component for verifying the SMS code during multi-factor enrollment.
+ *
+ * @returns The verify phone number form component.
+ */
 export function MultiFactorEnrollmentVerifyPhoneNumberForm(props: MultiFactorEnrollmentVerifyPhoneNumberFormProps) {
   const ui = useUI();
   const form = useMultiFactorEnrollmentVerifyPhoneNumberForm({
@@ -227,10 +266,20 @@ export function MultiFactorEnrollmentVerifyPhoneNumberForm(props: MultiFactorEnr
   );
 }
 
+/** Props for the SmsMultiFactorEnrollmentForm component. */
 export type SmsMultiFactorEnrollmentFormProps = {
+  /** Optional callback function called when enrollment is successful. */
   onSuccess?: () => void;
 };
 
+/**
+ * A form component for SMS multi-factor authentication enrollment.
+ *
+ * Handles the two-step process: first entering the phone number and display name, then verifying the SMS code.
+ *
+ * @returns The SMS multi-factor enrollment form component.
+ * @throws {Error} Throws an error if the user is not authenticated.
+ */
 export function SmsMultiFactorEnrollmentForm(props: SmsMultiFactorEnrollmentFormProps) {
   const ui = useUI();
 

packages/react/src/auth/forms/mfa/totp-multi-factor-assertion-form.tsx

@@ -20,6 +20,11 @@ import { signInWithMultiFactorAssertion, FirebaseUIError, getTranslation } from
 import { form } from "~/components/form";
 import { useMultiFactorTotpAuthVerifyFormSchema, useUI } from "~/hooks";
 
+/**
+ * Creates a memoized action function for verifying a TOTP code during multi-factor assertion.
+ *
+ * @returns A callback function that verifies the TOTP code and signs in with the multi-factor assertion.
+ */
 export function useTotpMultiFactorAssertionFormAction() {
   const ui = useUI();
 
@@ -32,11 +37,20 @@ export function useTotpMultiFactorAssertionFormAction() {
   );
 }
 
+/** Options for the TOTP multi-factor assertion form hook. */
 export type UseTotpMultiFactorAssertionForm = {
+  /** The multi-factor info hint containing TOTP information. */
   hint: MultiFactorInfo;
+  /** Callback function called when verification is successful. */
   onSuccess: (credential: UserCredential) => void;
 };
 
+/**
+ * Creates a form hook for TOTP multi-factor assertion verification code input.
+ *
+ * @param options - The TOTP assertion form options.
+ * @returns A form instance configured for TOTP verification code input.
+ */
 export function useTotpMultiFactorAssertionForm({ hint, onSuccess }: UseTotpMultiFactorAssertionForm) {
   const action = useTotpMultiFactorAssertionFormAction();
   const schema = useMultiFactorTotpAuthVerifyFormSchema();
@@ -59,11 +73,21 @@ export function useTotpMultiFactorAssertionForm({ hint, onSuccess }: UseTotpMult
   });
 }
 
+/** Props for the TotpMultiFactorAssertionForm component. */
 export type TotpMultiFactorAssertionFormProps = {
+  /** The multi-factor info hint containing TOTP information. */
   hint: MultiFactorInfo;
+  /** Optional callback function called when multi-factor assertion is successful. */
   onSuccess?: (credential: UserCredential) => void;
 };
 
+/**
+ * A form component for TOTP multi-factor authentication assertion.
+ *
+ * Allows users to enter a 6-digit TOTP code from their authenticator app.
+ *
+ * @returns The TOTP multi-factor assertion form component.
+ */
 export function TotpMultiFactorAssertionForm(props: TotpMultiFactorAssertionFormProps) {
   const ui = useUI();
   const form = useTotpMultiFactorAssertionForm({