@equinor/fusion-framework-react-app 9.0.9-next.0 → 10.0.0

package/src/ag-grid/useTheme.ts

@@ -2,6 +2,13 @@ import { useAppModule } from '../useAppModule';
 import type { AgGridModule } from '@equinor/fusion-framework-module-ag-grid';
 import type { Theme } from '@equinor/fusion-framework-module-ag-grid/themes';
 
+/**
+ * React hook that returns the current AG Grid theme from the application-scoped
+ * AG Grid module.
+ *
+ * @returns The active {@link Theme} object.
+ * @throws If the AG Grid module is not registered in the application.
+ */
 export const useTheme = (): Theme => {
   const agGrid = useAppModule<AgGridModule>('agGrid');
 

package/src/analytics/index.ts

@@ -1 +1,9 @@
+/**
+ * Analytics sub-path entry-point.
+ *
+ * Provides the {@link useTrackFeature} hook for tracking application-level
+ * analytics events through the Fusion analytics module.
+ *
+ * @packageDocumentation
+ */
 export { useTrackFeature } from './useTrackFeature';

package/src/analytics/useTrackFeature.ts

@@ -4,7 +4,23 @@ import type { AnalyticsModule, AnyValueMap } from '@equinor/fusion-framework-mod
 import { useCallback } from 'react';
 
 /**
- * Hook for using analytics module configured in the framework.
+ * React hook that returns a callback for tracking application feature usage
+ * via the Fusion analytics module.
+ *
+ * The tracked event includes the current app key and context (if available)
+ * as attributes, enabling downstream analytics dashboards to group events
+ * by application and context.
+ *
+ * @returns A `trackFeature` callback: `(name: string, data?: AnyValueMap) => void`.
+ *
+ * @example
+ * ```tsx
+ * const trackFeature = useTrackFeature();
+ *
+ * const handleClick = useCallback(() => {
+ *   trackFeature('button-click', { section: 'header' });
+ * }, [trackFeature]);
+ * ```
  */
 export const useTrackFeature = () => {
   const analyticsProvider = useFrameworkModule<AnalyticsModule>('analytics');

package/src/apploader/index.ts

@@ -1,2 +1,10 @@
+/**
+ * Apploader sub-path entry-point.
+ *
+ * Provides the {@link Apploader} component and {@link useApploader} hook
+ * for embedding Fusion child applications inside a parent Fusion application.
+ *
+ * @packageDocumentation
+ */
 export { Apploader, type ApploaderProps } from './Apploader';
 export { useApploader } from './useApploader';

package/src/bookmark/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Bookmark sub-path entry-point.
+ *
+ * Provides helpers to enable and consume the Fusion bookmark module,
+ * allowing users to save and restore application state snapshots.
+ *
+ * @packageDocumentation
+ */
 export { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';
 
 export { useCurrentBookmark } from './useCurrentBookmark';

package/src/context/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Context sub-path entry-point.
+ *
+ * Provides hooks for reading and interacting with the Fusion context
+ * (project, facility, etc.) at both the application and framework level.
+ *
+ * @packageDocumentation
+ */
 export * from '@equinor/fusion-framework-react-module-context';
 
 export { useContextProvider } from './useContextProvider';

package/src/context/useContextProvider.ts

@@ -1,6 +1,12 @@
 import type { ContextModule } from '@equinor/fusion-framework-react-module-context';
 import { useAppModule } from '../useAppModule';
 
+/**
+ * React hook that resolves the application-scoped context module provider.
+ *
+ * @returns The context module provider instance.
+ * @throws If the context module is not registered in the application scope.
+ */
 export const useContextProvider = () => useAppModule<ContextModule>('context');
 
 export default useContextProvider;

package/src/context/useCurrentContext.ts

@@ -1,6 +1,20 @@
 import { useCurrentContext as _useCurrentContext } from '@equinor/fusion-framework-react-module-context';
 import useContextProvider from './useContextProvider';
 
+/**
+ * React hook that returns the currently selected Fusion context from the
+ * **application-scoped** context module.
+ *
+ * @returns The current context object, or `undefined` if no context is selected.
+ *
+ * @example
+ * ```tsx
+ * const context = useCurrentContext();
+ * if (context) {
+ *   console.log('Selected:', context.title);
+ * }
+ * ```
+ */
 export const useCurrentContext = () => _useCurrentContext(useContextProvider());
 
 export default useCurrentContext;

package/src/create-legacy-app.tsx

@@ -8,6 +8,19 @@ import type { AppEnv, AppModuleInitiator } from '@equinor/fusion-framework-app';
 import { createComponent } from './create-component';
 import type { AppModule } from '@equinor/fusion-framework-module-app';
 
+/**
+ * Creates a legacy wrapper component that bootstraps a Fusion React app within
+ * the older Fusion CLI hosting model.
+ *
+ * @deprecated Prefer {@link renderApp} for new applications. This helper exists
+ * only for backward-compatibility with apps that must run inside the legacy
+ * Fusion CLI.
+ *
+ * @template TModules - Array of additional module types to initialise.
+ * @param Component - The root React element to render.
+ * @param configure - Optional callback to configure application modules.
+ * @returns A React function component that initialises modules and renders the app.
+ */
 export const createLegacyApp = <TModules extends Array<AnyModule>>(
   Component: ElementType,
   configure?: AppModuleInitiator<TModules>,

package/src/feature-flag/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Feature-flag sub-path entry-point.
+ *
+ * Provides the {@link enableFeatureFlag} configurator helper and the
+ * {@link useFeature} hook for reading and toggling feature flags at runtime.
+ *
+ * @packageDocumentation
+ */
 export {
   IFeatureFlag,
   IFeatureFlagProvider,

package/src/feature-flag/useFeature.ts

@@ -13,10 +13,26 @@ import { findFeature } from '@equinor/fusion-framework-module-feature-flag/selec
 import { useAppModule } from '../useAppModule';
 
 /**
- * Custom hook for accessing and manipulating feature flags.
- * @template T - The type of the feature flag value.
- * @param key - The key of the feature flag.
- * @returns An object containing the feature flag, toggle function, and error (if any).
+ * React hook for reading and toggling a single feature flag.
+ *
+ * Merges feature flags from both the framework and the application scope,
+ * so framework-level flags are visible alongside app-specific ones.
+ *
+ * @template T - The type of the feature flag's value payload.
+ * @param key - The unique key identifying the feature flag.
+ * @returns An object with:
+ *   - `feature` – the resolved {@link IFeatureFlag}, or `undefined` if not found.
+ *   - `toggleFeature` – callback to toggle the flag; pass `true`/`false` to
+ *     set explicitly, or omit to invert the current state.
+ *   - `error` – any error from the feature-flag observable.
+ *
+ * @example
+ * ```tsx
+ * const { feature, toggleFeature } = useFeature('dark-mode');
+ * return (
+ *   <Switch checked={feature?.enabled} onChange={() => toggleFeature()} />
+ * );
+ * ```
  */
 export const useFeature = <T = unknown>(
   key: string,

package/src/framework/index.ts

@@ -1,6 +1,13 @@
+/**
+ * Framework sub-path entry-point.
+ *
+ * Re-exports framework-level hooks (as opposed to application-scoped ones)
+ * for accessing the Fusion instance, current user, and HTTP clients.
+ *
+ * @packageDocumentation
+ */
 export { useFramework } from '@equinor/fusion-framework-react';
 
-// TODO
 export {
   useCurrentUser,
   useHttpClient as useFrameworkHttpClient,

package/src/framework/useFrameworkCurrentContext.ts

@@ -1,6 +1,15 @@
 import { useFramework } from '@equinor/fusion-framework-react';
 import { useCurrentContext } from '@equinor/fusion-framework-react-module-context';
 
+/**
+ * React hook that returns the currently selected context from the
+ * **framework-level** context module (as opposed to the application-scoped one).
+ *
+ * Use this when you need the portal/host context rather than the app's own
+ * context provider.
+ *
+ * @returns The current framework context, or `undefined` if none is selected.
+ */
 export const useFrameworkCurrentContext = () => useCurrentContext(useFramework().modules.context);
 
 export default useFrameworkCurrentContext;

package/src/help-center/useHelpCenter.ts

@@ -77,7 +77,18 @@ export interface HelpCenter {
 }
 
 /**
- * Hook for accessing help center.
+ * React hook that returns an API for opening the portal help-center sidesheet.
+ *
+ * Each method dispatches a framework event that the portal shell listens for
+ * and opens the corresponding help page.
+ *
+ * @returns A {@link HelpCenter} object with methods to open specific help pages.
+ *
+ * @example
+ * ```tsx
+ * const helpCenter = useHelpCenter();
+ * <Button onClick={() => helpCenter.openFaqs()}>FAQs</Button>
+ * ```
  */
 export const useHelpCenter = (): HelpCenter => {
   const eventModule = useAppModule('event');

package/src/http/index.ts

@@ -1 +1,10 @@
+/**
+ * HTTP sub-path entry-point.
+ *
+ * Re-exports hooks from `@equinor/fusion-framework-react-module-http`,
+ * including {@link useHttpClient} for making authenticated HTTP requests
+ * from within a Fusion application.
+ *
+ * @packageDocumentation
+ */
 export * from '@equinor/fusion-framework-react-module-http';

package/src/http/selectors.ts

@@ -1 +1,9 @@
+/**
+ * HTTP selector utilities.
+ *
+ * Re-exports response-selector helpers (e.g. JSON, blob, text selectors)
+ * from `@equinor/fusion-framework-module-http/selectors`.
+ *
+ * @packageDocumentation
+ */
 export * from '@equinor/fusion-framework-module-http/selectors';

package/src/index.ts

@@ -1,3 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * React bindings for building Fusion Framework applications.
+ *
+ * Provides the main entry-point helpers (`renderApp`, `createComponent`, `makeComponent`)
+ * plus React hooks for accessing framework modules (HTTP, auth, context, navigation, etc.)
+ * from within a Fusion app.
+ *
+ * @remarks
+ * This is the primary package application developers depend on when building
+ * React-based Fusion apps. It re-exports core types from `@equinor/fusion-framework-app`
+ * and adds React-specific rendering, hooks, and sub-path entry-points for optional
+ * modules such as MSAL, feature flags, bookmarks, analytics, and settings.
+ */
+
 export type {
   AppConfig,
   AppEnv,

package/src/make-component.tsx

@@ -13,11 +13,26 @@ import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framewo
 
 import { ModuleProvider as AppModuleProvider } from '@equinor/fusion-framework-react-module';
 
+/**
+ * Arguments supplied when rendering a Fusion app component.
+ *
+ * @template TFusion - The Fusion framework instance type.
+ * @template TEnv - The application environment type.
+ */
 export type ComponentRenderArgs<TFusion extends Fusion = Fusion, TEnv = AppEnv> = {
+  /** The Fusion framework instance. */
   fusion: TFusion;
+  /** The application environment (manifest, config, basename, etc.). */
   env: TEnv;
 };
 
+/**
+ * Factory function that receives a Fusion instance and environment and returns a
+ * lazy React component ready to be rendered.
+ *
+ * @template TFusion - The Fusion framework instance type.
+ * @template TEnv - The application environment type.
+ */
 export type ComponentRenderer<TFusion extends Fusion = Fusion, TEnv = AppEnv> = (
   fusion: TFusion,
   env: TEnv,

package/src/msal/index.ts

@@ -1,3 +1,16 @@
+/**
+ * MSAL authentication sub-path entry-point.
+ *
+ * Provides React hooks for accessing MSAL-based authentication state
+ * (current account, access tokens) from within a Fusion application.
+ *
+ * @remarks
+ * Requires `@equinor/fusion-framework-module-msal` to be installed and
+ * configured by the host/portal. Applications should **not** configure the
+ * MSAL module themselves.
+ *
+ * @packageDocumentation
+ */
 export { useCurrentAccount } from './useCurrentAccount';
 export { useAccessToken } from './useAccessToken';
 export { useToken } from './useToken';

package/src/msal/useAccessToken.ts

@@ -1,10 +1,22 @@
 import { useToken } from './useToken';
 
 /**
- * Custom hook that retrieves an access token for the specified authentication request.
+ * React hook that acquires an OAuth 2.0 access token string via MSAL.
  *
- * @param req - The authentication request.
- * @returns An object containing the access token, pending state, and error.
+ * This is a convenience wrapper around {@link useToken} that extracts the
+ * `accessToken` property from the full `AuthenticationResult`.
+ *
+ * @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 access token string, or `undefined` while pending.
+ *   - `pending` – `true` while the token is being acquired.
+ *   - `error` – any error encountered during acquisition.
+ *
+ * @example
+ * ```tsx
+ * const { token, pending, error } = useAccessToken({ scopes: ['api://my-api/.default'] });
+ * ```
  */
 export const useAccessToken = (req: {
   scopes: string[];

package/src/msal/useCurrentAccount.ts

@@ -2,8 +2,18 @@ import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
 import useAppModule from '../useAppModule';
 
 /**
- * Retrieves the current account information from the MSAL provider.
- * @returns The current account information or undefined if no account is available.
+ * React hook that returns the currently signed-in user's MSAL account info.
+ *
+ * @returns The {@link AccountInfo} for the active account, or `undefined` if
+ *   no user is signed in.
+ *
+ * @example
+ * ```tsx
+ * const account = useCurrentAccount();
+ * if (account) {
+ *   console.log('Signed in as', account.name);
+ * }
+ * ```
  */
 export const useCurrentAccount = (): AccountInfo | undefined => {
   const msalProvider = useAppModule('auth');

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

@@ -4,11 +4,26 @@ import { renderComponent, type RenderTeardown } from './render-component';
 import type { ComponentRenderArgs } from './create-component';
 
 /**
- * Creates a render function for an app component.
- * Uses React 18's createRoot API via renderComponent.
+ * Creates a render function for a Fusion React application.
  *
- * @param componentArgs - Arguments to pass to createComponent
- * @returns A function that renders the app into a DOM element
+ * 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));

package/src/render-component.tsx

@@ -3,14 +3,21 @@ import type { FunctionComponent } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { ComponentRenderArgs, ComponentRenderer } from './create-component';
 
+/**
+ * Callback returned after mounting an application; invoke it to unmount and clean
+ * up the React root.
+ */
 export type RenderTeardown = VoidFunction;
 
 /**
- * Renders a React component into a DOM element using React 18's createRoot API.
+ * Renders a React component into a DOM element using React 18's `createRoot` API.
  *
- * @param el - The DOM element to render into
- * @param Component - The React component to render
- * @returns A teardown function that unmounts the component
+ * 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 => {
   const root: Root = createRoot(el);
@@ -27,11 +34,16 @@ const render = (el: Element, Component: FunctionComponent): RenderTeardown => {
 };
 
 /**
- * Creates a render function for a component renderer.
- * Uses React 18's createRoot API instead of the deprecated ReactDOM.render.
+ * 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 function that creates a component from fusion and env
- * @returns A function that renders the component into a DOM element
+ * @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 => {

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

@@ -3,10 +3,16 @@ 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,

package/src/version.ts

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

package/vitest.config.ts

@@ -1,17 +1,12 @@
 import { defineProject } from 'vitest/config';
-import tsconfigPaths from 'vite-tsconfig-paths';
-import { fileURLToPath } from 'node:url';
-import { resolve } from 'node:path';
 
 import { name, version } from './package.json';
 
 export default defineProject({
-  plugins: [
-    tsconfigPaths({
-      root: resolve(fileURLToPath(new URL('../../..', import.meta.url))),
-      projects: [resolve(fileURLToPath(new URL('.', import.meta.url)), 'tsconfig.json')],
-    }),
-  ],
+  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}`,