Additional msal-react v5 migration details (#8386)

This pull request updates the migration documentation for both MSAL
Browser and MSAL React to clarify the required steps for upgrading to
v5, including payload type changes, migration paths, and compatibility
notes. The changes provide explicit migration examples and highlight new
requirements and breaking changes.

**MSAL React v5 Migration Guidance and Compatibility:**

- Added clear migration paths for upgrading from v1/v2/v3 to v5, with
emphasis on following the MSAL Browser v4-v5 migration guide and setting
up the required COOP redirect bridge.
- Documented React version support: MSAL React v5 now requires React
19+, with notes and workarounds for temporary use on React 18, though it
is not supported.

**MSAL Browser v5 Event Handling Changes:**

- Provided explicit guidance on handling the new `LOGIN_SUCCESS` payload
type, including before/after TypeScript code samples to illustrate the
migration from casting to `AuthenticationResult` to using `AccountInfo`.

**InteractionStatus and Event Consolidation:**

- Clarified the consolidation of `InteractionStatus` values and provided
a migration example for simplifying in-progress status checks in React
apps.

These updates ensure developers have clear, actionable steps for
migrating to the latest major versions and handling breaking changes in
event payloads and interaction status.

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tnorling <5307810+tnorling@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

lib/msal-browser/docs/v4-migration.md

@@ -418,6 +418,46 @@ We have consolidated event types and InteractionStatus to reflect what happened
 1. The payload for `LOGIN_SUCCESS` is now an `AccountInfo` object.
 1. Any successful login now emits both a `LOGIN_SUCCESS` and `ACQUIRE_TOKEN_SUCCESS` event.
 
+#### `LOGIN_SUCCESS` payload type migration
+
+If your event callback currently casts `LOGIN_SUCCESS` payloads to `AuthenticationResult`, update it to use `AccountInfo` for `LOGIN_SUCCESS` and reserve `AuthenticationResult` for `ACQUIRE_TOKEN_SUCCESS`.
+
+```typescript
+// BEFORE (v4-style assumption)
+import {
+    EventType,
+    AuthenticationResult,
+} from "@azure/msal-browser";
+
+pca.addEventCallback((event) => {
+    if (event.eventType === EventType.LOGIN_SUCCESS) {
+        const result = event.payload as AuthenticationResult;
+        setAccount(result.account); // Will silently fail in v5 where payload is AccountInfo, not AuthenticationResult
+    }
+});
+```
+
+```typescript
+// AFTER (v5-safe handling)
+import {
+    EventType,
+    AuthenticationResult,
+    AccountInfo,
+} from "@azure/msal-browser";
+
+pca.addEventCallback((event) => {
+    if (event.eventType === EventType.LOGIN_SUCCESS) {
+        const account = event.payload as AccountInfo;
+        setAccount(account);
+    }
+
+    if (event.eventType === EventType.ACQUIRE_TOKEN_SUCCESS) {
+        const result = event.payload as AuthenticationResult;
+        setAccessToken(result.accessToken);
+    }
+});
+```
+
 ### Error message format changes
 
 To reduce bundle size, error messages have been moved out of the bundle. When an error is thrown, the `message` property now returns a generic link to the error documentation instead of a descriptive error message:

lib/msal-react/docs/migration-guide-v4-v5.md

@@ -4,11 +4,54 @@ Note: There is no MSAL React v4 release. The package version was incremented fro
 
 Please see the [MSAL Browser v4-v5 migration guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v4-migration.md) for browser support and other key changes.
 
+## Migration paths
+
+- **v3 -> v5**: Follow this guide, then apply the [MSAL Browser v4-v5 migration guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v4-migration.md), especially the COOP redirect bridge setup.
+- **v1/v2 -> v5**: The v1 -> v2 and v2 -> v3 updates were peer dependency version updates only for most apps. Move to v3 first, then follow the v3 -> v5 guidance in this document plus COOP redirect bridge setup.
+
+## COOP redirect bridge setup (required)
+
+MSAL Browser v5 requires a dedicated redirect page/bridge for authentication flows.
+
+Please see the [COOP section in the MSAL Browser v4-v5 migration guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/v4-migration.md#cross-origin-opener-policy-coop-support).
+
 ## Dropped support for old React versions
-MSAL React v5 supports React 19 or greater. It no longer supports React 16, 17, or 18.
+MSAL React v5 supports React 19.2.1 or greater. It no longer supports React 16, 17, or 18.
+
+## React 18 compatibility note
+
+If your app is still on React 18, installing `@azure/msal-react@^5` may fail due to peer dependency constraints.
+
+- Temporary install workaround: `npm install --legacy-peer-deps`
+- This may allow installation and basic flows may continue to work in some apps, but React 18 is not supported or validated for v5
+- You may see untested behavior around rendering/lifecycle timing, StrictMode interactions, or future patch updates
+
+For production workloads, upgrade React to 19.2.1 or greater before moving to `@azure/msal-react@^5`.
 
 ## Correct logout bug
 MSAL React v5 has fixed a bug affecting the `useMsalAuthentication` hook and `MsalAuthenticationTemplate`. Logging out now clears all state associated with the user.
 
 ## `InteractionStatus` changes
-For `InteractionStatus`: `Login`, `SsoSilent`, and `AcquireToken` are now consolidated into `AcquireToken`.
+For `InteractionStatus`: `Login`, `SsoSilent`, and `AcquireToken` are now consolidated into `AcquireToken`.
+
+### Migration example
+
+If your app previously checked multiple in-progress statuses, simplify to the consolidated `AcquireToken` status.
+
+```ts
+import { InteractionStatus } from "@azure/msal-browser";
+
+// Before (v3-style checks)
+const tokenInteractionInProgress =
+	inProgress === InteractionStatus.Login ||
+	inProgress === InteractionStatus.SsoSilent ||
+	inProgress === InteractionStatus.AcquireToken;
+
+// After (v5)
+const tokenInteractionInProgress =
+	inProgress === InteractionStatus.AcquireToken;
+
+if (!tokenInteractionInProgress) {
+	// safe to initiate a new auth/token request
+}
+```