@equinor/fusion-framework-dev-portal 5.0.0-next.0 → 5.0.1

package/CHANGELOG.md

@@ -1,36 +1,108 @@
 # @equinor/fusion-framework-dev-portal
 
-## 5.0.0-next.0
+## 5.0.1
+
+### Patch Changes
+
+- ed3786d: Internal: update `@equinor/fusion-wc-person` from `^3.4.0` to `^3.4.1` for the development and people provider packages; no public API changes.
+- Updated dependencies [ed3786d]
+  - @equinor/fusion-framework-react-components-people-provider@2.0.1
+
+## 5.0.0
+
+### Major Changes
+
+- abffa53: Major version bump for Fusion Framework React 19 release.
+
+  All packages are bumped to the next major version as part of the React 19 upgrade. This release drops support for React versions below 18 and includes breaking changes across the framework.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React Router upgraded from v6 to v7
+  - Navigation module refactored with new history API
+  - `renderComponent` and `renderApp` now use `createRoot` API
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading
+  - Replace `NavigationProvider.createRouter()` with `@equinor/fusion-framework-react-router`
+  - See individual package changelogs for package-specific migration steps
+
+- abffa53: Upgrade to React 19 and remove support for React versions lower than 18.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React 16 and 17 are no longer supported
+  - Dev dependencies upgraded to React 19.2.1 and @types/react 19.2.7
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading these packages
+  - If using React 16 or 17, upgrade to React 18 or 19 first
+
+  Closes https://github.com/equinor/fusion-framework/issues/3504
 
 ### Minor Changes
 
-- [#3820](https://github.com/equinor/fusion-framework/pull/3820) [`fa89ed8`](https://github.com/equinor/fusion-framework/commit/fa89ed8aeed919950ef6a6775e60eb6904ec7946) Thanks [@odinr](https://github.com/odinr)! - Update EDS (Equinor Design System) packages to latest versions: `@equinor/eds-core-react` to ^2.2.0, `@equinor/eds-icons` to ^1.1.0, `@equinor/eds-tokens` to ^2.1.1, and `@equinor/eds-utils` to ^2.0.0.
+- abffa53: Update EDS (Equinor Design System) packages to latest versions: `@equinor/eds-core-react` to ^2.2.0, `@equinor/eds-icons` to ^1.1.0, `@equinor/eds-tokens` to ^2.1.1, and `@equinor/eds-utils` to ^2.0.0.
 
   These are major version updates from the 0.x series. Consumers should verify compatibility with their applications, particularly if using `@equinor/fusion-react-side-sheet` which may require updates to support the new EDS versions.
 
 ### Patch Changes
 
-- [#3820](https://github.com/equinor/fusion-framework/pull/3820) [`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78) Thanks [@odinr](https://github.com/odinr)! - relase next
-
-- Updated dependencies [[`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78), [`fa89ed8`](https://github.com/equinor/fusion-framework/commit/fa89ed8aeed919950ef6a6775e60eb6904ec7946)]:
-  - @equinor/fusion-framework-react-components-people-provider@1.6.4-next.0
-  - @equinor/fusion-framework-react-components-bookmark@1.2.0-next.0
-  - @equinor/fusion-framework-react-module-bookmark@5.0.3-next.0
-  - @equinor/fusion-framework-module-feature-flag@1.1.29-next.0
-  - @equinor/fusion-framework-module-navigation@7.0.0-next.2
-  - @equinor/fusion-framework-module-telemetry@4.6.5-next.0
-  - @equinor/fusion-observable@8.5.9-next.0
-  - @equinor/fusion-framework-react@7.4.21-next.0
-  - @equinor/fusion-framework-module-app@7.4.2-next.0
-  - @equinor/fusion-query@6.0.5-next.0
-  - @equinor/fusion-framework-app@10.4.10-next.0
-  - @equinor/fusion-framework-dev-server@1.1.32-next.0
-  - @equinor/fusion-framework@7.4.14-next.0
-  - @equinor/fusion-framework-module-ag-grid@35.1.0-next.0
-  - @equinor/fusion-framework-module-bookmark@3.0.7-next.0
-  - @equinor/fusion-framework-module-context@7.0.4-next.0
-  - @equinor/fusion-framework-module-services@7.2.2-next.0
-  - @equinor/fusion-framework-module-analytics@1.0.3-next.0
+- abffa53: Render application content inside a stable `#app-section` container so browser-driven evaluation tools can target the app surface consistently.
+
+  This makes automated cookbook and dev-portal validation more reliable when using `agent-browser` and Copilot-based evaluation flows.
+
+  Refs https://github.com/equinor/fusion-core-tasks/issues/724
+
+- abffa53: Upgrade dev-portal dependencies for React 19 compatibility.
+  - Upgrade `react-router` from v6 to v7.13 (backward-compatible, no code changes required)
+  - Upgrade `@equinor/fusion-react-styles` to 2.0.0 (removes `@material-ui/styles` dependency)
+  - Upgrade `@equinor/fusion-react-context-selector` to 2.0.1
+
+  This resolves the React 19 blocker identified in https://github.com/equinor/fusion-framework/issues/3698
+
+- abffa53: Upgrade `react-router-dom` from v6 to v7.9.5 for React 19 compatibility.
+
+  This is a backward-compatible upgrade - all existing Router 6 patterns continue to work with Router 7. No code changes required.
+
+- aa35c46: chore: bump @vitejs/plugin-react from 5.1.4 to 6.0.1
+- 32bcf83: Bump `vite` from `7.3.1` to `8.0.0`.
+
+  Vite 8 replaces Rollup with Rolldown and esbuild with Oxc for faster builds.
+  No breaking API changes affect this codebase. The `dev-server` peerDependency
+  is widened to accept both Vite 7 and Vite 8.
+
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [aa35c46]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [aaa3f74]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [32bcf83]
+  - @equinor/fusion-framework@8.0.0
+  - @equinor/fusion-framework-app@11.0.0
+  - @equinor/fusion-framework-dev-server@2.0.0
+  - @equinor/fusion-framework-module-ag-grid@36.0.0
+  - @equinor/fusion-framework-module-analytics@2.0.0
+  - @equinor/fusion-framework-module-app@8.0.0
+  - @equinor/fusion-framework-module-bookmark@4.0.0
+  - @equinor/fusion-framework-module-context@8.0.0
+  - @equinor/fusion-framework-module-feature-flag@2.0.0
+  - @equinor/fusion-framework-module-navigation@7.0.0
+  - @equinor/fusion-framework-module-services@8.0.0
+  - @equinor/fusion-framework-module-telemetry@5.0.0
+  - @equinor/fusion-framework-react@8.0.0
+  - @equinor/fusion-framework-react-components-bookmark@2.0.0
+  - @equinor/fusion-framework-react-components-people-provider@2.0.0
+  - @equinor/fusion-framework-react-module-bookmark@6.0.0
+  - @equinor/fusion-observable@9.0.0
+  - @equinor/fusion-query@7.0.0
 
 ## 4.0.4
 

package/README.md

@@ -1,11 +1,19 @@
-## Dev Portal
+# @equinor/fusion-framework-dev-portal
 
-This package provides a development portal for the Fusion framework.
+Minimal development portal for building and testing Fusion Framework applications locally.
 
-This Portal only contains the bare minimum to get started with the Fusion Application development. Visuals might differ from the production portal.
+## What Is It?
 
-It is recommended to use the `@equinor/fusion-framework-dev-server` package for a more complete development experience.
-This package is a small part of the refactoring of the `@equinor/fusion-framework-cli` and is not intended for direct use in production.
+`@equinor/fusion-framework-dev-portal` provides a lightweight portal shell that mirrors the production Fusion portal layout — header, context selector, bookmark side sheet, person settings, and application routing — without the full production overhead. It is the portal component loaded by `@equinor/fusion-framework-dev-server` and `@equinor/fusion-framework-cli` when running apps locally.
+
+Use this package when you need a portal host for local app development. For the recommended development workflow, pair it with `@equinor/fusion-framework-dev-server`.
+
+## Key Concepts
+
+- **Portal shell**: A React application that renders the top bar, context selector, and an app mounting area.
+- **Application loader**: Dynamically initializes and mounts a Fusion app by its `appKey`, handling manifest resolution, script loading, and teardown.
+- **Framework modules**: The portal pre-configures telemetry, navigation, bookmarks, feature flags, analytics, AG Grid, and service integrations so loaded apps inherit a realistic environment.
+- **Context navigation**: When an app uses the context module, the portal synchronizes URL navigation with context changes automatically.
 
 ## Installation
 
@@ -15,55 +23,55 @@ pnpm add @equinor/fusion-framework-dev-portal
 
 ## Environment Variables
 
-The following environment variables must be set in `.env` or in the environment variables of the server:
+Set these in a `.env` file or in your server environment:
 
-- FUSION_MSAL_CLIENT_ID: The client ID for MSAL authentication.
-- FUSION_MSAL_TENANT_ID: The tenant ID for MSAL authentication.
-- FUSION_SERVICE_DISCOVERY_URL: The URL for service discovery.
-- FUSION_SERVICE_SCOPE: The scopes for the service.
-- FUSION_SPA_AG_GRID_KEY: (Optional) AG Grid Enterprise license key for local development. When provided, this eliminates AG Grid license console warnings when running the portal locally with AG Grid-enabled features.
+| Variable | Required | Description |
+|---|---|---|
+| `FUSION_MSAL_CLIENT_ID` | Yes | MSAL application client ID for authentication |
+| `FUSION_MSAL_TENANT_ID` | Yes | Azure AD tenant ID for authentication |
+| `FUSION_SERVICE_DISCOVERY_URL` | Yes | URL for the Fusion service discovery endpoint |
+| `FUSION_SERVICE_SCOPE` | Yes | OAuth scopes for service requests |
+| `FUSION_SPA_AG_GRID_KEY` | No | AG Grid Enterprise license key — silences console warnings locally |
 
-### Local AG Grid Configuration
+### AG Grid License
 
-To use AG Grid Enterprise features without console warnings during local development:
+To suppress AG Grid Enterprise license warnings during local development:
 
-1. Obtain an AG Grid Enterprise license key from your organization
-2. Add the key to your `.env` file:
-   ```sh
-   FUSION_SPA_AG_GRID_KEY=your-license-key-here
-   ```
-3. Start the dev portal:
-   ```sh
-   pnpm start
-   ```
-4. Verify the configuration by opening the portal and checking the browser console - there should be no AG Grid license warnings
+1. Add `FUSION_SPA_AG_GRID_KEY=<your-key>` to your `.env` file.
+2. Start the dev portal with `pnpm start`.
+3. Verify the browser console shows no AG Grid license warnings.
 
-**Note**: The license key is only used for local development and is never committed to the repository or deployed to production.
+The license key is only used locally and must not be committed to the repository.
 
-## Development
+## Quick Start
 
 ```sh
 pnpm start
 ```
 
-## Usage
+This launches the dev server with the portal loaded.
+
+## Public API
+
+The package exports a single `render` function that mounts the portal into a DOM element:
 
 ```ts
-import { render } from "@equinor/fusion-framework-dev-portal";
+import { render } from '@equinor/fusion-framework-dev-portal';
 
-const el = document.createElement("div");
-el.id = "dev-portal";
+const el = document.createElement('div');
+el.id = 'dev-portal';
 document.body.appendChild(el);
 
-const framework = /** Fusion Framework, [Service Discovery, MSAL] */;
-
-render(el, {ref: framework});
+// `framework` is a pre-configured Fusion Framework instance with Service Discovery and MSAL
+render(el, { ref: framework });
 ```
 
 ### Usage with `@equinor/fusion-framework-dev-server`
 
+The dev server loads this portal automatically. A typical integration looks like:
+
 ```ts
-import { createDevServer } from "@equinor/fusion-framework-dev-server";
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
 
 const portalId = '@equinor/fusion-framework-dev-portal';
 const devServer = await createDevServer({
@@ -72,33 +80,31 @@ const devServer = await createDevServer({
       portal: {
         id: portalId,
         tag: 'latest',
-      }
-      /** --- Add any other environment variables you need here --- */
+      },
     },
   },
   api: {
-    serviceDiscoveryUrl: "https://location.of.your.service.discovery",
-    processServices: /** generate proxy routes */
-    routes: [
-      {
-        // intercept for the dev-portal manifest
-        match: `/PROXY_SERVICE_KEY/PROXY_PATH/${options.portal}{@:tag}`,
-        middleware: async (req, res) => {
-          res.writeHead(200, { 'content-type': 'application/json' });
-          // resolve the local path to the dev-portal
-          // __CWD__/node_modules/@equinor/fusion-framework-dev-portal/dist/main.js
-          const path =  fileURLToPath('/@fs' + import.meta.resolve(portalId));
-          const manifest = {
-            build: { 
-              entrypoint: new URL(path, req.headers.referer), 
-            }
-          }
-          res.end(JSON.stringify(manifest));
-        },
-      }
-    ]
+    serviceDiscoveryUrl: 'https://location.of.your.service.discovery',
   },
 });
 ```
 
+## Architecture
+
+The portal is composed of these internal parts:
+
+- **`render`** — Entry point; creates a React root with theme, framework, and people-resolver providers.
+- **`configure`** — Configures all framework modules (telemetry, navigation, bookmarks, feature flags, analytics, AG Grid, services).
+- **`Router`** — Sets up routes with `react-router` via the navigation module; routes `/apps/:appKey/*` to the app loader.
+- **`AppLoader`** — Resolves, initializes, and mounts a Fusion app by key; handles loading states and errors.
+- **`Header`** — Top bar with the Fusion logo, context selector, bookmark toggle, and person settings.
+- **`ContextSelector`** — Wired to the current app's context module for searching and selecting context items.
+- **`useAppContextNavigation`** — Synchronizes URL pathname with context changes for apps that use the context module.
+
+## Constraints
+
+- This portal is for **local development only** and is not intended for production deployment.
+- Visuals may differ from the production Fusion portal.
+- The portal assumes MSAL and service discovery are configured in the parent framework instance.
+