@equinor/fusion-framework-react-app 9.0.8 → 10.0.0

package/src/msal/useToken.ts

@@ -5,9 +5,25 @@ import type { AuthenticationResult } from '@equinor/fusion-framework-module-msal
 import useAppModule from '../useAppModule';
 
 /**
- * Custom hook for acquiring an authentication token using MSAL.
- * @param req - The authentication request.
- * @returns An object containing the acquired token, pending state, and error.
+ * React hook that acquires a full MSAL {@link AuthenticationResult} for the
+ * requested scopes.
+ *
+ * The hook attempts silent acquisition first and falls back to an interactive
+ * prompt when required by the MSAL provider.
+ *
+ * @param req - The token request containing the `scopes` to acquire.
+ * @param req.scopes - Array of scope strings (e.g. `['User.Read']`).
+ * @returns An object with:
+ *   - `token` – the full {@link AuthenticationResult}, or `undefined` while pending.
+ *   - `pending` – `true` while the token is being acquired.
+ *   - `error` – any error encountered during acquisition.
+ *
+ * @example
+ * ```tsx
+ * const { token, pending } = useToken({ scopes: ['User.Read'] });
+ * if (pending) return <Spinner />;
+ * console.log('ID token:', token?.idToken);
+ * ```
  */
 export const useToken = (req: {
   scopes: string[];

package/src/navigation/index.ts

@@ -1,2 +1,10 @@
+/**
+ * Navigation sub-path entry-point.
+ *
+ * Provides hooks for accessing the Fusion navigation module and creating
+ * client-side routers compatible with `react-router`.
+ *
+ * @packageDocumentation
+ */
 export { useNavigationModule } from './useNavigationModule';
 export { useRouter } from './useRouter';

package/src/navigation/useNavigationModule.ts

@@ -1,5 +1,10 @@
 import useAppModule from '../useAppModule';
 import type { INavigationProvider } from '@equinor/fusion-framework-module-navigation';
 
-/** hook for getting the navigation provider (if enabled!) */
+/**
+ * React hook that resolves the application-scoped navigation module provider.
+ *
+ * @returns The navigation provider instance.
+ * @throws If the navigation module has not been enabled for the application.
+ */
 export const useNavigationModule = (): INavigationProvider => useAppModule('navigation');

package/src/navigation/useRouter.ts

@@ -3,10 +3,29 @@ import { useNavigationModule } from './useNavigationModule';
 import type { INavigationProvider } from '@equinor/fusion-framework-module-navigation';
 
 /**
- * create a router for react routing
- * @see {@link [docs](https://equinor.github.io/fusion-framework/modules/navigation/)}
- * @see {@link [react-router](https://reactrouter.com/en/main/routers/create-browser-router)}
- * @param routes router objects __(must be static | memorized)__
+ * React hook that creates a router instance for client-side navigation.
+ *
+ * The `routes` argument **must** be static or memoised to avoid re-creating
+ * the router on every render.
+ *
+ * @param routes - An array of route objects compatible with
+ *   `INavigationProvider.createRouter`.
+ * @returns A router instance to pass to `<RouterProvider>`.
+ *
+ * @see {@link https://equinor.github.io/fusion-framework/modules/navigation/ | Fusion navigation docs}
+ * @see {@link https://reactrouter.com/en/main/routers/create-browser-router | react-router docs}
+ *
+ * @example
+ * ```tsx
+ * import { useRouter } from '@equinor/fusion-framework-react-app/navigation';
+ * import { RouterProvider } from 'react-router-dom';
+ *
+ * const routes = [{ path: '/', element: <Home /> }];
+ * const App = () => {
+ *   const router = useRouter(routes);
+ *   return <RouterProvider router={router} />;
+ * };
+ * ```
  */
 export const useRouter = (
   routes: Parameters<INavigationProvider['createRouter']>[0],

package/src/render-app.ts

@@ -3,7 +3,28 @@ import { renderComponent, type RenderTeardown } from './render-component';
 
 import type { ComponentRenderArgs } from './create-component';
 
-/** @deprecated */
+/**
+ * Creates a render function for a Fusion React application.
+ *
+ * Wraps {@link createComponent} and {@link renderComponent} into a single factory:
+ * call the returned function with an `HTMLElement` and `ComponentRenderArgs` to
+ * mount the app using React 18's `createRoot` API.
+ *
+ * @param componentArgs - Arguments forwarded to {@link createComponent} (the React
+ *   component to render and an optional module-configuration callback).
+ * @returns A mount function that accepts a DOM element and render args, and returns
+ *   a {@link RenderTeardown} callback to unmount the application.
+ *
+ * @example
+ * ```ts
+ * import { renderApp } from '@equinor/fusion-framework-react-app';
+ * import { App } from './App';
+ * import { configure } from './config';
+ *
+ * export const render = renderApp(App, configure);
+ * export default render;
+ * ```
+ */
 export const renderApp = (...componentArgs: Parameters<typeof createComponent>) => {
   const renderer = renderComponent(createComponent(...componentArgs));
   return (el: HTMLElement, args: ComponentRenderArgs): RenderTeardown => {

package/src/render-component.tsx

@@ -1,46 +1,55 @@
 import { Suspense, StrictMode } from 'react';
 import type { FunctionComponent } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
 import type { ComponentRenderArgs, ComponentRenderer } from './create-component';
-import ReactDOM from 'react-dom';
 
+/**
+ * Callback returned after mounting an application; invoke it to unmount and clean
+ * up the React root.
+ */
 export type RenderTeardown = VoidFunction;
 
-/** @deprecated */
-export const renderComponent = (renderer: ComponentRenderer) => {
-  return (el: HTMLElement, args: ComponentRenderArgs): RenderTeardown => {
-    const Component = renderer(args.fusion, args.env);
-    return render(el, Component);
-  };
-};
-
+/**
+ * Renders a React component into a DOM element using React 18's `createRoot` API.
+ *
+ * The component is wrapped in `<StrictMode>` and `<Suspense>` with a basic
+ * loading fallback.
+ *
+ * @param el - The DOM element to render into.
+ * @param Component - The React function component to render.
+ * @returns A {@link RenderTeardown} callback that unmounts the component.
+ */
 const render = (el: Element, Component: FunctionComponent): RenderTeardown => {
-  // eslint-disable-next-line react/no-deprecated
-  ReactDOM.render(
+  const root: Root = createRoot(el);
+  root.render(
     <StrictMode>
       <Suspense fallback={<p>loading app</p>}>
         <Component />
       </Suspense>
     </StrictMode>,
-    el,
   );
   return () => {
-    // eslint-disable-next-line react/no-deprecated
-    ReactDOM.unmountComponentAtNode(el);
+    root.unmount();
   };
 };
 
-// const render = (el: Element, Component: FunctionComponent): RenderTeardown => {
-//     const root = createRoot(el);
-//     root.render(
-//         <StrictMode>
-//             <Suspense fallback={<p>loading app</p>}>
-//                 <Component />
-//             </Suspense>
-//         </StrictMode>
-//     );
-//     return () => {
-//         root.unmount();
-//     };
-// };
+/**
+ * Creates a mount function from a {@link ComponentRenderer}.
+ *
+ * The returned function accepts a target `HTMLElement` and
+ * {@link ComponentRenderArgs}, resolves the lazy component via the renderer,
+ * and mounts it with React 18's `createRoot`.
+ *
+ * @param renderer - A {@link ComponentRenderer} that produces a lazy component
+ *   from Fusion and environment arguments.
+ * @returns A function `(el, args) => RenderTeardown` that mounts the app and
+ *   returns a teardown callback.
+ */
+export const renderComponent = (renderer: ComponentRenderer) => {
+  return (el: HTMLElement, args: ComponentRenderArgs): RenderTeardown => {
+    const Component = renderer(args.fusion, args.env);
+    return render(el, Component);
+  };
+};
 
 export default renderComponent;

package/src/settings/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Settings sub-path entry-point.
+ *
+ * Provides hooks for reading and updating per-application user settings
+ * that are persisted by the Fusion platform.
+ *
+ * @packageDocumentation
+ */
 export { useAppSetting } from './useAppSetting';
 export { useAppSettings } from './useAppSettings';
 

package/src/useAppModule.ts

@@ -9,12 +9,20 @@ import type {
 import { useAppModules } from './useAppModules';
 
 /**
- * Retrieves the specified app module from the app scope.
+ * React hook that retrieves a single module instance from the application scope.
  *
- * @template TType - The type of the app module.
- * @template TKey - The key of the app module.
- * @param module - The key of the app module to retrieve.
- * @returns The app module instance if found, otherwise throws an error.
+ * @template TType - The concrete module type (e.g. `ContextModule`). Pass
+ *   `unknown` to infer the type from the key.
+ * @template TKey - The string key used to look up the module.
+ * @param module - The key identifying the module to retrieve.
+ * @returns The resolved module instance.
+ * @throws If the requested module is not registered in the application scope.
+ *
+ * @example
+ * ```tsx
+ * const auth = useAppModule('auth');
+ * auth.acquireAccessToken().then(console.log);
+ * ```
  */
 export function useAppModule<
   TType extends AnyModule | unknown = unknown,

package/src/useAppModules.ts

@@ -1,15 +1,21 @@
-import type { AppModulesInstance } from '@equinor/fusion-framework-app';
+import type { AppModules, AppModulesInstance } from '@equinor/fusion-framework-app';
 import type { AnyModule } from '@equinor/fusion-framework-module';
 import { useModules } from '@equinor/fusion-framework-react-module';
 
 /**
- * Custom hook that returns an instance of the app modules.
+ * React hook that returns the full set of initialised application-scoped modules.
  *
- * @template T - The type of the app modules.
- * @returns An instance of the app modules.
+ * @template T - Optional array of additional module types beyond the defaults.
+ * @returns The {@link AppModulesInstance} containing all registered modules.
+ *
+ * @example
+ * ```tsx
+ * const modules = useAppModules();
+ * console.log(Object.keys(modules));
+ * ```
  */
 export const useAppModules = <
   T extends Array<AnyModule> | unknown = unknown,
->(): AppModulesInstance<T> => useModules<AppModulesInstance<T>>();
+>(): AppModulesInstance<T> => useModules<AppModules<T>>() as AppModulesInstance<T>;
 
 export default useAppModules;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '9.0.8';
+export const version = '10.0.0';

package/tsconfig.json

@@ -38,5 +38,5 @@
     }
   ],
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib"]
+  "exclude": ["node_modules", "lib", "src/__tests__/**/*"]
 }

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineProject } from 'vitest/config';
+
+import { name, version } from './package.json';
+
+export default defineProject({
+  resolve: {
+    // @ts-expect-error -- tsconfigPaths is a Vite 8 option; vitest 4.x ships Vite 7 types
+    tsconfigPaths: true,
+  },
+  test: {
+    include: ['src/__tests__/**'],
+    name: `${name}@${version}`,
+    environment: 'happy-dom',
+  },
+});