@equinor/fusion-framework-react-app 7.0.1 → 8.0.0-next.1

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.1";
+export declare const version = "8.0.0-next.1";

package/docs/msal.md

@@ -0,0 +1,291 @@
+# MSAL Authentication
+
+This package includes React hooks for Microsoft authentication using MSAL v4.
+
+> [!CAUTION]
+> **Applications should NOT configure the MSAL module themselves.**
+>
+> The MSAL module **must be configured by the host/portal application**, not by individual apps. This is required for module hoisting, which allows sharing authentication state across all applications in a portal.
+>
+> - ✅ **Host/Portal:** Configure MSAL using `enableMSAL()` in the portal's configuration
+> - ❌ **App:** Do NOT call `enableMSAL()` or configure the auth module
+> - ✅ **App:** Just use the hooks to access the already-configured MSAL module
+
+> [!IMPORTANT]
+> `@equinor/fusion-framework-module-msal` must be installed to make MSAL hooks available
+
+## Overview
+
+The MSAL authentication hooks provide a simple way to integrate Microsoft authentication into your React applications. These hooks are built on top of `@equinor/fusion-framework-module-msal` and provide React-friendly access to authentication state and token acquisition.
+
+Since the MSAL module is configured by your host application, you don't need to worry about configuration—just import and use the hooks!
+
+The hooks use a simplified API that internally handles the MSAL v4 format, so you can use the simple `{ scopes: string[] }` format without worrying about the v4 nested request structure.
+
+## Available Hooks
+
+### useCurrentAccount
+
+Returns the current authenticated user account information.
+
+**Signature:**
+```typescript
+useCurrentAccount(): AccountInfo | undefined
+```
+
+**Example:**
+```tsx
+import { useCurrentAccount } from '@equinor/fusion-framework-react-app/msal';
+
+const UserProfile = () => {
+  const account = useCurrentAccount();
+  
+  if (!account) {
+    return <span>Not authenticated</span>;
+  }
+  
+  return (
+    <div>
+      <p>Username: {account.username}</p>
+      <p>Name: {account.name}</p>
+      <p>Tenant ID: {account.tenantId}</p>
+    </div>
+  );
+};
+```
+
+**Returns:** `AccountInfo | undefined`
+
+### useAccessToken
+
+Returns just the access token string for making authenticated API calls.
+
+**Signature:**
+```typescript
+useAccessToken(req: { scopes: string[] }): { token?: string; pending: boolean; error: unknown }
+```
+
+**Example:**
+```tsx
+import { useAccessToken } from '@equinor/fusion-framework-react-app/msal';
+import { useMemo } from 'react';
+
+const ProtectedComponent = () => {
+  const { token, pending, error } = useAccessToken(
+    useMemo(() => ({ scopes: ['User.Read'] }), [])
+  );
+  
+  if (pending) return <span>Loading token...</span>;
+  if (error) return <span>Error: {String(error)}</span>;
+  
+  return token ? <span>Token acquired</span> : <span>No token</span>;
+};
+```
+
+**Parameters:**
+- `req`: Object with `scopes` property - Array of OAuth scopes to request
+
+**Returns:** 
+- `token?: string` - The access token string if available
+- `pending: boolean` - Whether the token request is in progress
+- `error: unknown` - Any error that occurred during token acquisition
+
+### useToken
+
+Returns the full authentication result object with complete token information.
+
+**Signature:**
+```typescript
+useToken(req: { scopes: string[] }): { token?: AuthenticationResult; pending: boolean; error: unknown }
+```
+
+**Example:**
+```tsx
+import { useToken } from '@equinor/fusion-framework-react-app/msal';
+import { useMemo } from 'react';
+
+const TokenInfo = () => {
+  const { token, pending, error } = useToken(
+    useMemo(() => ({ scopes: ['User.Read', 'api.read'] }), [])
+  );
+  
+  if (pending) return <span>Loading...</span>;
+  if (error) return <span>Error: {String(error)}</span>;
+  if (!token) return <span>No token</span>;
+  
+  return (
+    <div>
+      <p>Access Token: {token.accessToken.substring(0, 20)}...</p>
+      <p>Expires: {new Date(token.expiresOn).toLocaleString()}</p>
+      <p>Token Type: {token.tokenType}</p>
+      <p>Scope: {token.scopes.join(', ')}</p>
+    </div>
+  );
+};
+```
+
+**Parameters:**
+- `req`: Object with `scopes` property - Array of OAuth scopes to request
+
+**Returns:**
+- `token?: AuthenticationResult` - Full authentication result containing accessToken, account info, expiresOn, etc.
+- `pending: boolean` - Whether the token request is in progress
+- `error: unknown` - Any error that occurred during token acquisition
+
+**Note:** The `AuthenticationResult` type includes:
+- `accessToken: string`
+- `account: AccountInfo`
+- `expiresOn: Date`
+- `tokenType: string`
+- `scopes: string[]`
+- And more...
+
+## How It Works
+
+Internally, these hooks call the MSAL provider's methods which support both legacy and modern formats:
+
+```typescript
+// The hook receives simple format:
+useToken({ scopes: ['User.Read'] })
+
+// Internally converts to MSAL v4 format:
+msalProvider.acquireToken({ request: { scopes: ['User.Read'] } })
+```
+
+This means you can use the simpler API without dealing with the v4 nested structure, while still benefiting from MSAL v4 features under the hood.
+
+## Complete Example
+
+```tsx
+import { useCurrentAccount, useAccessToken } from '@equinor/fusion-framework-react-app/msal';
+import { useMemo, useState } from 'react';
+
+const App = () => {
+  const account = useCurrentAccount();
+  
+  // Get scopes from somewhere (e.g., service discovery)
+  const [scopes] = useState(['User.Read', 'api.read']);
+  
+  const { token, pending, error } = useAccessToken(
+    useMemo(() => ({ scopes }), [scopes])
+  );
+
+  return (
+    <div>
+      {!account && <p>Please log in</p>}
+      
+      {account && (
+        <>
+          <h1>Welcome, {account.name}!</h1>
+          <p>Username: {account.username}</p>
+          
+          {pending && <p>Loading token...</p>}
+          {error && <p>Error: {String(error)}</p>}
+          {token && (
+            <div>
+              <p>Token acquired successfully</p>
+              <pre>{token.substring(0, 50)}...</pre>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+```
+
+## Advanced Usage
+
+### Dynamic Scopes
+
+```tsx
+const Component = () => {
+  const [scopes, setScopes] = useState(['User.Read']);
+  
+  const { token, pending } = useAccessToken(
+    useMemo(() => ({ scopes }), [scopes])
+  );
+  
+  return (
+    <div>
+      <button onClick={() => setScopes(['User.Read', 'api.write'])}>
+        Request More Permissions
+      </button>
+      {token && <p>Token ready</p>}
+    </div>
+  );
+};
+```
+
+### Error Handling
+
+```tsx
+const Component = () => {
+  const { token, error, pending } = useAccessToken(
+    useMemo(() => ({ scopes: ['User.Read'] }), [])
+  );
+  
+  useEffect(() => {
+    if (error) {
+      console.error('Token acquisition failed:', error);
+      // Handle error appropriately
+    }
+  }, [error]);
+  
+  return pending ? <Loading /> : token ? <Content /> : <Error />;
+};
+```
+
+## Performance Considerations
+
+1. **Memoize request objects**: Always wrap the scopes object in `useMemo` to prevent unnecessary re-renders
+   ```tsx
+   // Bad - creates new object on every render
+   const { token } = useAccessToken({ scopes: ['User.Read'] });
+   
+   // Good - stable reference
+   const { token } = useAccessToken(
+     useMemo(() => ({ scopes: ['User.Read'] }), [])
+   );
+   ```
+
+2. **Dependent scopes**: Include scopes in the dependency array
+   ```tsx
+   const { token } = useAccessToken(
+     useMemo(() => ({ scopes }), [scopes])
+   );
+   ```
+
+## MSAL v4 Under the Hood
+
+While the hooks use a simple API, they internally use MSAL v4:
+
+- Hooks accept `{ scopes: string[] }` for simplicity
+- Internally converts to `{ request: { scopes: string[] } }` format
+- The provider supports both legacy and modern formats
+- All benefits of MSAL v4 are available (better security, performance, etc.)
+
+## Troubleshooting
+
+### Hook Returns No Account
+
+- Ensure user is logged in
+- Check that MSAL module is properly configured
+- Verify `useCurrentAccount()` hook is wrapped in a component within the framework provider
+
+### Token Acquisition Fails
+
+- Verify scopes are properly configured in Azure AD
+- Check user has necessary permissions for requested scopes
+- Review browser console for MSAL errors
+
+### Performance Issues
+
+- Ensure scopes object is memoized with `useMemo`
+- Check for unnecessary re-renders of parent components
+
+## Related Documentation
+
+- [MSAL Module Documentation](https://equinor.github.io/fusion-framework/modules/auth/msal/) - Core MSAL provider
+- [Microsoft MSAL Browser Docs](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser) - Official MSAL documentation
+- [Azure AD App Registration Guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) - App registration guide

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "7.0.1",
+  "version": "8.0.0-next.1",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -106,13 +106,13 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-app": "^10.1.1",
-    "@equinor/fusion-framework-module": "^5.0.4",
-    "@equinor/fusion-framework-module-app": "^7.0.2",
-    "@equinor/fusion-framework-module-navigation": "^6.0.0",
-    "@equinor/fusion-framework-react": "^7.4.18",
-    "@equinor/fusion-framework-react-module": "^3.1.13",
-    "@equinor/fusion-framework-react-module-http": "^10.0.0"
+    "@equinor/fusion-framework-app": "^10.1.2-next.1",
+    "@equinor/fusion-framework-module-app": "^7.0.4-next.0",
+    "@equinor/fusion-framework-react": "^7.4.19-next.1",
+    "@equinor/fusion-framework-module": "^5.0.6-next.0",
+    "@equinor/fusion-framework-module-navigation": "^6.0.1-next.0",
+    "@equinor/fusion-framework-react-module": "^3.1.14-next.0",
+    "@equinor/fusion-framework-react-module-http": "^10.0.1-next.1"
   },
   "devDependencies": {
     "@types/react": "^18.2.50",
@@ -121,20 +121,20 @@
     "react-dom": "^18.2.0",
     "rxjs": "^7.8.1",
     "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-ag-grid": "^34.2.1",
-    "@equinor/fusion-framework-module-event": "^4.4.0",
-    "@equinor/fusion-framework-module-feature-flag": "^1.1.25",
-    "@equinor/fusion-framework-module-msal": "^5.1.1",
-    "@equinor/fusion-framework-react-module-bookmark": "^5.0.1",
-    "@equinor/fusion-framework-react-module-context": "^6.2.33",
-    "@equinor/fusion-observable": "^8.5.5"
+    "@equinor/fusion-framework-module-ag-grid": "^34.2.3-next.0",
+    "@equinor/fusion-framework-module-event": "^4.4.1-next.0",
+    "@equinor/fusion-framework-module-feature-flag": "^1.1.27-next.0",
+    "@equinor/fusion-framework-module-msal": "^6.0.0-next.1",
+    "@equinor/fusion-framework-react-module-bookmark": "^5.0.2-next.1",
+    "@equinor/fusion-framework-react-module-context": "^6.2.34-next.0",
+    "@equinor/fusion-observable": "^8.5.7-next.0"
   },
   "peerDependencies": {
     "@types/react": "^17.0.0 || ^18.0.0",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0",
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module-msal": "^5.1.1"
+    "@equinor/fusion-framework-module-msal": "^6.0.0-next.1"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-react-module-ag-grid": {

package/src/msal/useCurrentAccount.ts

@@ -7,5 +7,5 @@ import useAppModule from '../useAppModule';
  */
 export const useCurrentAccount = (): AccountInfo | undefined => {
   const msalProvider = useAppModule('auth');
-  return msalProvider.defaultAccount;
+  return msalProvider.account || undefined;
 };

package/src/msal/useToken.ts

@@ -20,9 +20,12 @@ export const useToken = (req: {
     setPending(true);
     setToken(undefined);
     msalProvider
-      .acquireToken(req)
-      // biome-ignore lint/suspicious/noConfusingVoidType: this method returns a void type when no token is acquired
-      .then((token: AuthenticationResult | void) => token && setToken(token))
+      .acquireToken({ request: req })
+      .then((result) => {
+        if (result) {
+          setToken(result);
+        }
+      })
       .catch(setError)
       .finally(() => setPending(false));
   }, [msalProvider, req]);

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.0.1';
+export const version = '8.0.0-next.1';