@equinor/fusion-framework-react-app 14.1.0 → 14.1.2

package/docs/msal.md

@@ -1,291 +0,0 @@
-# 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: {token.expiresOn?.toLocaleString() ?? 'unknown'}</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 | null`
-- `expiresOn: Date | null`
-- `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/docs/navigation.md

@@ -1,80 +0,0 @@
-# Navigation
-
-Set up client-side routing in your Fusion app using the framework-managed navigation module.
-
-**Import:**
-
-```ts
-import { useRouter, useNavigationModule } from '@equinor/fusion-framework-react-app/navigation';
-```
-
-## Overview
-
-The navigation module wraps React Router with Fusion's base path handling, ensuring your app's routes work correctly under the portal's URL structure (e.g. `/apps/my-app/...`). Use `useRouter` to create a router instance and pass it to `<RouterProvider>`.
-
-> [!IMPORTANT]
-> Do not use `createBrowserRouter` from React Router directly — it bypasses the Fusion base path and will cause routing conflicts inside the portal.
-
-## Enable Navigation
-
-The navigation module must be enabled in your app's configurator. Always pass the basename so routes resolve correctly under the portal's URL prefix:
-
-```ts
-import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
-
-export const configure = (configurator) => {
-  // Pass the basename that matches where the portal mounts your app.
-  // In a Fusion portal this is typically the app's appKey path, e.g. '/apps/my-app'.
-  enableNavigation(configurator, '/apps/my-app');
-};
-```
-
-Without a basename, routes will not be prefixed and will conflict with the portal's URL structure.
-
-## useRouter
-
-Creates a router instance from route definitions. The returned router is compatible with `<Router>` from `@equinor/fusion-framework-react-router`.
-
-> [!WARNING]
-> `useRouter` calls `INavigationProvider.createRouter()`, which is **deprecated** in the navigation module and emits a telemetry warning at runtime. For new apps, prefer `<Router>` from `@equinor/fusion-framework-react-router` directly — it handles the basename and Fusion context automatically without requiring `useRouter`.
-
-> [!CAUTION]
-> **Routes must be stable or memoised.** If you pass a new array reference on every render, the router will be recreated each time, resetting navigation state. Define routes outside the component or use `useMemo`.
-
-### Minimal Routing Example
-
-```tsx
-import { useRouter } from '@equinor/fusion-framework-react-app/navigation';
-import { Router } from '@equinor/fusion-framework-react-router';
-
-const Home = () => <h1>Home</h1>;
-const Settings = () => <h1>Settings</h1>;
-
-// Define routes outside the component to keep them stable
-const routes = [
-  { path: '/', element: <Home /> },
-  { path: '/settings', element: <Settings /> },
-];
-
-const App = () => {
-  const router = useRouter(routes);
-  return <Router router={router} />;
-};
-```
-
-## useNavigationModule
-
-Returns the navigation module provider instance directly. Use this for advanced scenarios where you need access to the full provider API (e.g. programmatic navigation outside of React Router's hooks).
-
-**Signature:**
-
-```ts
-function useNavigationModule(): INavigationProvider;
-```
-
-**Throws** if the navigation module has not been enabled for the application.
-
-## Prerequisites
-
-- The navigation module must be enabled in your app's configurator via `enableNavigation`
-- Do not mix `useRouter` with direct `createBrowserRouter` calls — use one approach consistently

package/docs/routing.md

@@ -1,86 +0,0 @@
-# Routing
-
-The `@equinor/fusion-framework-react-app/routing` entry point re-exports the full public API of
-`@equinor/fusion-framework-react-router` — including the `<Router>` component, the route builder
-DSL, all React Router hooks, and types — so you can import everything from a single package without
-adding `@equinor/fusion-framework-react-router` as a direct dependency.
-
-## Installation
-
-`@equinor/fusion-framework-react-router` is an **optional peer dependency**. Install it alongside the app package:
-
-```bash
-pnpm add @equinor/fusion-framework-react-router
-```
-
-## Usage
-
-```ts
-import { Router } from '@equinor/fusion-framework-react-app/routing';
-import { layout, index, route, prefix } from '@equinor/fusion-framework-react-app/routing';
-```
-
-Everything exported from `@equinor/fusion-framework-react-router` and its `/routes` DSL is
-available from this single entry point.
-
-## Enable navigation in your configurator
-
-The `<Router>` component reads `history` and `basename` from the Fusion navigation module.
-Enable it in your configurator before mounting:
-
-```ts
-import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
-import type { IAppConfigurator, AppEnv, Fusion } from '@equinor/fusion-framework-react-app';
-
-export const configure = (
-  configurator: IAppConfigurator,
-  args: { fusion: Fusion; env: AppEnv },
-) => {
-  enableNavigation(configurator, {
-    configure: (config) => {
-      config.setBasename(args.env.basename);
-    },
-  });
-};
-```
-
-## Define routes
-
-```ts
-// src/routes.ts
-import { layout, index, route, prefix } from '@equinor/fusion-framework-react-app/routing';
-
-export default layout('./Layout.tsx', [
-  index('./pages/HomePage.tsx'),
-  prefix('products', [
-    index('./pages/ProductsPage.tsx'),
-    route(':id', './pages/ProductPage.tsx'),
-  ]),
-]);
-```
-
-## Mount the Router
-
-```tsx
-// src/Router.tsx
-import { Router } from '@equinor/fusion-framework-react-app/routing';
-import routes from './routes';
-
-export default function AppRouter() {
-  return <Router routes={routes} />;
-}
-```
-
-## Use routing hooks
-
-All React Router hooks are re-exported from the same entry point:
-
-```tsx
-import { useNavigate, useParams, useLocation, Link } from '@equinor/fusion-framework-react-app/routing';
-```
-
-## See also
-
-- [Getting started](/modules/react/router/getting-started) — full setup walkthrough for the standalone router package
-- [Interop entry point](/modules/react/router/interop) — `MemoryRouter` and other react-router bridges for testing and mid-migration
-- [Migration guide](/modules/react/router/migration) — moving from a plain react-router setup

package/docs/settings.md

@@ -1,139 +0,0 @@
-# Settings
-
-Persist and read app-specific user settings using the Fusion settings service.
-
-**Import:**
-
-```ts
-import { useAppSetting, useAppSettings } from '@equinor/fusion-framework-react-app/settings';
-```
-
-## Overview
-
-App settings let users customise their experience (theme, layout, filters) with values persisted per-user by the Fusion platform. The `useAppSetting` hook manages a single setting, while `useAppSettings` provides access to all settings at once.
-
-## Type Your Settings
-
-Use module augmentation to get type-safe setting keys and values:
-
-```ts
-declare module '@equinor/fusion-framework-react-app/settings' {
-  interface AppSettings {
-    theme: 'default' | 'light' | 'dark';
-    mode: 'simple' | 'advanced';
-  }
-}
-```
-
-## useAppSetting
-
-Manages a single setting by key. Returns the current value and a setter function, similar to `useState`.
-
-**Signature:**
-
-```ts
-function useAppSetting<TSettings, TProp extends keyof TSettings>(
-  prop: TProp,
-  defaultValue?: TSettings[TProp],
-  hooks?: AppSettingsStatusHooks & {
-    onError?: (error: Error | null) => void;
-    onUpdated?: () => void;
-  },
-): [TSettings[TProp] | undefined, (update: TSettings[TProp] | ((current: TSettings[TProp] | undefined) => TSettings[TProp])) => void];
-```
-
-### Example
-
-```tsx
-import { useCallback } from 'react';
-import { useAppSetting } from '@equinor/fusion-framework-react-app/settings';
-
-const ThemeSwitcher = () => {
-  const [theme, setTheme] = useAppSetting('theme', 'default');
-  const [mode, setMode] = useAppSetting('mode', 'simple');
-
-  const toggleMode = useCallback(() => {
-    setMode((current) => (current === 'simple' ? 'advanced' : 'simple'));
-  }, [setMode]);
-
-  return (
-    <div>
-      {/* cast: e.target.value is string, but setTheme expects the union type */}
-      <select value={theme ?? 'default'} onChange={(e) => setTheme(e.target.value as AppSettings['theme'])}>
-        <option value="default">Default</option>
-        <option value="light">Light</option>
-        <option value="dark">Dark</option>
-      </select>
-      <button onClick={toggleMode}>Toggle mode ({mode})</button>
-    </div>
-  );
-};
-```
-
-## useAppSettings
-
-Returns all settings as a single object with a bulk setter. Use `useAppSetting` for individual settings when possible — `useAppSettings` triggers a re-render on _any_ setting change.
-
-**Signature:**
-
-```ts
-function useAppSettings<TSettings>(
-  defaultValue?: TSettings,
-  hooks?: AppSettingsStatusHooks & {
-    onError?: (error: Error | null) => void;
-    onUpdated?: () => void;
-  },
-): [TSettings, (update: TSettings | ((current: TSettings | undefined) => TSettings)) => void];
-```
-
-> [!WARNING]
-> **`setSettings` must include all settings, not just the ones you want to change.** Use a callback to merge with the current state:
->
-> ```ts
-> setSettings((current) => ({ ...current, theme: 'dark' }));
-> ```
-
-### Example
-
-```tsx
-import { useCallback } from 'react';
-import { useAppSettings } from '@equinor/fusion-framework-react-app/settings';
-
-const SettingsPanel = () => {
-  const [settings, setSettings] = useAppSettings();
-
-  const updateTheme = useCallback(
-    (theme: AppSettings['theme']) => setSettings((current) => ({ ...current, theme })),
-    [setSettings],
-  );
-
-  return <ThemeSelector value={settings?.theme} onChange={updateTheme} />;
-};
-```
-
-## Status Hooks
-
-Both hooks accept optional status callbacks for loading, updating, and error states:
-
-```tsx
-const [loading, setLoading] = useState(false);
-const [updating, setUpdating] = useState(false);
-const [error, setError] = useState<Error | null>(null);
-
-const [theme, setTheme] = useAppSetting('theme', 'default', {
-  onLoading: setLoading,
-  onUpdating: setUpdating,
-  onError: setError,
-  onUpdated: useCallback(() => console.log('Saved'), []),
-});
-```
-
-> [!NOTE]
-> `onUpdating` and `onLoading` reflect the _global_ settings state, not individual settings. Disable update buttons while either is `true`.
-
-## Notes
-
-- Settings are async — there is a loading phase when the component mounts and an updating phase when values are saved
-- `useAppSetting` captures the `hooks` object once on mount (via `useState`); **the callbacks must be stable before the first render** — changes after mount are ignored
-- `useAppSettings` reads `hooks` on every render; **memoise callbacks** (e.g. with `useCallback`) to avoid unnecessary re-renders
-- Settings are persisted per-user per-app by the Fusion platform

package/src/__tests__/Apploader.test.tsx

@@ -1,51 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { mockFramework } from '@equinor/fusion-framework/mock';
-import { enableAppManifestMock } from '@equinor/fusion-framework-app/mock';
-import type { AppManifest, AppModule } from '@equinor/fusion-framework-module-app';
-
-import { Apploader } from '../apploader/Apploader';
-import { renderAppComponent } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
-
-// resolved from this test file rather than hardcoded, so it survives a package move
-const fixturesUri = new URL('./fixtures', import.meta.url).pathname;
-
-describe('Apploader', () => {
-  it('mounts the child app’s rendered content once its script loads', async () => {
-    const manifest: AppManifest = {
-      appKey: 'child-app',
-      displayName: 'Child App',
-      description: 'A child application',
-      type: 'standalone',
-      build: { version: '1.0.0', entryPoint: 'apploader-child-script.ts', assetPath: '' },
-    };
-
-    const fusion = await mockFramework<[AppModule]>((configurator) =>
-      enableAppManifestMock(configurator, { manifest }, fixturesUri),
-    );
-
-    const { container } = await renderAppComponent(<Apploader appKey="child-app" />, { fusion });
-
-    // the loading state renders synchronously, before the script's dynamic import resolves
-    expect(container.textContent).toContain('Loading child-app');
-    await vi.waitFor(() => expect(container.textContent).toContain('mounted: child-app'));
-  });
-
-  it('surfaces the load error instead of throwing when the app’s script fails to import', async () => {
-    const manifest: AppManifest = {
-      appKey: 'broken-app',
-      displayName: 'Broken App',
-      description: 'An application whose build entry point does not exist',
-      type: 'standalone',
-      build: { version: '1.0.0', entryPoint: 'does-not-exist.ts', assetPath: '' },
-    };
-
-    const fusion = await mockFramework<[AppModule]>((configurator) =>
-      enableAppManifestMock(configurator, { manifest }, fixturesUri),
-    );
-
-    const { container } = await renderAppComponent(<Apploader appKey="broken-app" />, { fusion });
-
-    await vi.waitFor(() => expect(container.textContent).toContain('Error loading broken-app'));
-  });
-});

package/src/__tests__/fixtures/apploader-child-script.ts

@@ -1,9 +0,0 @@
-import type { AppScriptModule } from '@equinor/fusion-framework-module-app';
-
-// a minimal stand-in for a real app bundle's entry point, dynamically imported by `App.initialize()`
-export const renderApp: AppScriptModule['renderApp'] = (el, { env }) => {
-  el.textContent = `mounted: ${env.manifest?.appKey}`;
-  return () => {
-    el.textContent = '';
-  };
-};