chore: cleanup

examples/react-spa/src/Login.tsx

@@ -4,11 +4,40 @@ import { useCallback, useEffect, useState } from "react"
 import { useNavigate, useSearchParams } from "react-router-dom"
 import { sdk, sdkError } from "./sdk"
 
+/**
+ * Login is a React component that renders the login form using Ory Elements.
+ * It is used to handle the login flow for a variety of authentication methods
+ * and authentication levels (e.g. Single-Factor and Two-Factor)
+ *
+ * The Login component also handles the OAuth2 login flow (as an OAuth2 provider)
+ * For more information regarding OAuth2 login, please see the following documentation:
+ * https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow
+ *
+ */
 export const Login = (): JSX.Element => {
   const [flow, setFlow] = useState<LoginFlow | null>(null)
   const [searchParams, setSearchParams] = useSearchParams()
+
+  // The aal is set as a query parameter by your Ory project
+  // aal1 is the default authentication level (Single-Factor)
+  // aal2 is a query parameter that can be used to request Two-Factor authentication
+  // https://www.ory.sh/docs/kratos/mfa/overview
   const aal2 = searchParams.get("aal2")
+
+  // The login_challenge is a query parameter set by the Ory OAuth2 login flow
+  // Switching between pages should keep the login_challenge in the URL so that the
+  // OAuth flow can be completed upon completion of another flow (e.g. Registration).
+  // https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow
   const loginChallenge = searchParams.get("login_challenge")
+
+  // The return_to is a query parameter is set by you when you would like to redirect
+  // the user back to a specific URL after login is successful
+  // In most cases it is not necessary to set a return_to if the UI business logic is
+  // handled by the SPA.
+  //
+  // In OAuth flows this value might be ignored in favor of keeping the OAuth flow
+  // intact between multiple flows (e.g. Login -> Recovery -> Settings -> OAuth2 Consent)
+  // https://www.ory.sh/docs/oauth2-oidc/identity-provider-integration-settings
   const returnTo = searchParams.get("return_to")
 
   const navigate = useNavigate()
@@ -30,9 +59,6 @@ export const Login = (): JSX.Element => {
   // Create a new login flow
   const createFlow = () => {
     sdk
-      // aal2 is a query parameter that can be used to request Two-Factor authentication
-      // aal1 is the default authentication level (Single-Factor)
-      // we always pass refresh (true) on login so that the session can be refreshed when there is already an active session
       .createBrowserLoginFlow({
         refresh: true,
         aal: aal2 ? "aal2" : "aal1",

examples/react-spa/src/Recovery.tsx

@@ -71,7 +71,18 @@ export const Recovery = () => {
       // the flow is always required since it contains the UI form elements, UI error messages and csrf token
       flow={flow}
       // the recovery form should allow users to navigate to the login page
-      additionalProps={{ loginURL: "/login" }}
+      additionalProps={{
+        loginURL: {
+          handler: () => {
+            navigate(
+              {
+                pathname: "/login",
+              },
+              { replace: true },
+            )
+          },
+        },
+      }}
       // submit the form data to Ory
       onSubmit={({ body }) => submitFlow(body as UpdateRecoveryFlowBody)}
     />

examples/react-spa/src/Registration.tsx

@@ -4,11 +4,30 @@ import { useCallback, useEffect, useState } from "react"
 import { useNavigate, useSearchParams } from "react-router-dom"
 import { sdk, sdkError } from "./sdk"
 
+/** Registration is a React component that renders the Registration form using Ory Elements.
+ * It is used to handle the registration flow for a variety of authentication methods.
+ *
+ * The Registration component also handles the OAuth2 registration flow (as an OAuth2 provider)
+ * For more information regarding OAuth2 registration, please see the following documentation:
+ * https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow
+ *
+ */
 export const Registration = () => {
   const [flow, setFlow] = useState<RegistrationFlow | null>(null)
   const [searchParams, setSearchParams] = useSearchParams()
 
+  // The return_to is a query parameter is set by you when you would like to redirect
+  // the user back to a specific URL after registration is successful
+  // In most cases it is not necessary to set a return_to if the UI business logic is
+  // handled by the SPA.
+  // In OAuth flows this value might be ignored in favor of keeping the OAuth flow
+  // intact between multiple flows (e.g. Login -> Recovery -> Settings -> OAuth2 Consent)
+  // https://www.ory.sh/docs/oauth2-oidc/identity-provider-integration-settings
   const returnTo = searchParams.get("return_to")
+
+  // The login_challenge is a query parameter set by the Ory OAuth2 registration flow
+  // Switching between pages should keep the login_challenge in the URL so that the
+  // OAuth flow can be completed upon completion of another flow (e.g. Login).
   const loginChallenge = searchParams.get("login_challenge")
 
   const navigate = useNavigate()

examples/react-spa/src/Verification.tsx

@@ -75,7 +75,11 @@ export const Verification = (): JSX.Element => {
       flow={flow}
       // we want users to be able to go back to the login page from the verification page
       additionalProps={{
-        signupURL: "/registration",
+        signupURL: {
+          handler: () => {
+            navigate({ pathname: "/registration" }, { replace: true })
+          },
+        },
       }}
       // submit the verification form data to Ory
       onSubmit={({ body }) => submitFlow(body as UpdateVerificationFlowBody)}