@equinor/fusion-framework-react-app 14.0.3 → 14.1.1

package/src/help-center/useHelpCenter.ts

@@ -1,162 +0,0 @@
-import { useCallback } from 'react';
-import useAppModule from '../useAppModule';
-
-import { EVENT_NAME } from './event-name.js';
-
-type HelpCenterEventDetailBase<
-  T extends string,
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  page: T;
-} & V;
-
-type OpenHelpDetail = HelpCenterEventDetailBase<'home'>;
-
-type OpenArticleDetail = HelpCenterEventDetailBase<
-  'article',
-  {
-    articleId: string;
-  }
->;
-
-type OpenFaqsDetail = HelpCenterEventDetailBase<'faqs'>;
-
-type OpenSearchDetail = HelpCenterEventDetailBase<
-  'search',
-  {
-    search: string;
-  }
->;
-
-type OpenGovernanceDetail = HelpCenterEventDetailBase<'governance'>;
-
-export type HelpCenterOpenEventDetail =
-  | OpenHelpDetail
-  | OpenArticleDetail
-  | OpenFaqsDetail
-  | OpenSearchDetail
-  | OpenGovernanceDetail;
-
-/**
- * Interface for requesting help features.
- */
-export interface HelpCenter {
-  /**
-   * Requesting the portal to open the help sidesheet on the normal page
-   */
-  openHelp(): void;
-
-  /**
-   * Requesting the portal to open the help sidesheet on the article page.
-   *
-   * @param {string} articleId - The articleId, slug or identifier to show.
-   */
-  openArticle(articleId: string): void;
-
-  /**
-   * Requesting the portal to open the help sidesheet on the FAQs page.
-   */
-  openFaqs(): void;
-
-  /**
-   * Requesting the portal to open the help sidesheet on the search page.
-   *
-   * @param {string} search - The search string.
-   */
-  openSearch(search: string): void;
-
-  /**
-   * Requesting the portal to open the help sidesheet on the governance tab.
-   */
-  openGovernance(): void;
-
-  /**
-   * Requesting the portal to open the help sidesheet on the release notes page.
-   */
-  openReleaseNotes(): void;
-}
-
-/**
- * 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');
-
-  const openHelp = useCallback((): void => {
-    eventModule.dispatchEvent(EVENT_NAME, {
-      detail: {
-        page: 'home',
-      },
-    });
-  }, [eventModule]);
-
-  const openArticle = useCallback(
-    (articleId: string): void => {
-      eventModule.dispatchEvent(EVENT_NAME, {
-        detail: {
-          page: 'article',
-          articleId: articleId,
-        },
-      });
-    },
-    [eventModule],
-  );
-
-  const openFaqs = useCallback((): void => {
-    eventModule.dispatchEvent(EVENT_NAME, {
-      detail: {
-        page: 'faqs',
-      },
-    });
-  }, [eventModule]);
-
-  const openSearch = useCallback(
-    (search: string): void => {
-      eventModule.dispatchEvent(EVENT_NAME, {
-        detail: {
-          page: 'search',
-          search: search,
-        },
-      });
-    },
-    [eventModule],
-  );
-
-  const openGovernance = useCallback((): void => {
-    eventModule.dispatchEvent(EVENT_NAME, {
-      detail: {
-        page: 'governance',
-      },
-    });
-  }, [eventModule]);
-
-  const openReleaseNotes = useCallback((): void => {
-    eventModule.dispatchEvent(EVENT_NAME, {
-      detail: {
-        page: 'release-notes',
-      },
-    });
-  }, [eventModule]);
-
-  return {
-    openHelp,
-    openArticle,
-    openFaqs,
-    openSearch,
-    openGovernance,
-    openReleaseNotes,
-  };
-};
-
-export default useHelpCenter;

package/src/http/index.ts

@@ -1,10 +0,0 @@
-/**
- * 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,9 +0,0 @@
-/**
- * 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,46 +0,0 @@
-/**
- * @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,
-  AppModuleInitiator,
-  AppModules,
-  AppModulesInstance,
-  AppRenderFn,
-  IAppConfigurator,
-} from '@equinor/fusion-framework-app';
-
-export type { Fusion } from '@equinor/fusion-framework-react';
-
-export { AppManifest } from '@equinor/fusion-framework-module-app';
-
-export { useAppModule } from './useAppModule';
-export { useAppModules } from './useAppModules';
-export { useAppEnvironmentVariables } from './useAppEnvironmentVariables';
-
-export { makeComponent, ComponentRenderArgs } from './make-component';
-
-export { createLegacyApp } from './create-legacy-app';
-
-export { createComponent } from './create-component';
-export { renderApp } from './render-app';
-export { renderComponent } from './render-component';
-
-export type { ComponentRenderer } from './create-component';
-export type { RenderTeardown } from './render-component';
-
-export { default } from './render-app';

package/src/make-component.tsx

@@ -1,102 +0,0 @@
-import type React from 'react';
-import { lazy } from 'react';
-
-import { FrameworkProvider } from '@equinor/fusion-framework-react';
-import type { Fusion } from '@equinor/fusion-framework-react';
-
-import { type AppEnv, configureModules } from '@equinor/fusion-framework-app';
-import type { AppModuleInitiator, AppModulesInstance } from '@equinor/fusion-framework-app';
-
-import type { AnyModule } from '@equinor/fusion-framework-module';
-
-import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-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,
-) => React.LazyExoticComponent<React.ComponentType>;
-
-/**
- * Creates a lazy loading React Component that initializes and configures modules,
- * then provides the necessary context to both the Fusion framework and the configured modules.
- * This function is particularly useful for setting up a React application with modular architecture,
- * allowing for lazy loading of components along with their dependencies.
- *
- * __Exposed providers__:
- * - {@link @equinor/fusion-framework-react.FrameworkProvider | FrameworkProvider} to provide Fusion context.
- * - {@link @equinor/fusion-framework-react-module.ModuleProvider | ModuleProvider} to provide module instances.
- *
- * @template TModules The types of modules included in the configuration.
- * @template TRef The type of the Fusion instance.
- * @template TEnv The environment type for the application.
- * @param {React.ReactNode} Component - The React component to render lazily.
- * @param {Object} args - The arguments required for module configuration and component rendering.
- * @param {TRef} args.fusion - The Fusion instance to be used by the component and modules.
- * @param {TEnv} args.env - The environment context for the application.
- * @param {AppModuleInitiator<TModules, TRef, TEnv>} [configure] - Optional callback function for configuring application modules.
- * @returns {React.LazyExoticComponent<React.ComponentType>} A lazy component that, when rendered,
- * initializes the specified modules and provides the necessary Fusion and module context.
- */
-export const makeComponent = <
-  TModules extends Array<AnyModule>,
-  TRef extends Fusion = Fusion,
-  TEnv extends AppEnv = AppEnv,
->(
-  Component: React.ReactNode,
-  args: { fusion: TRef; env: TEnv },
-  configure?: AppModuleInitiator<TModules, TRef, TEnv>,
-): React.LazyExoticComponent<React.ComponentType> =>
-  lazy(async () => {
-    const init = configureModules<TModules, TRef, TEnv>(configure);
-    const modules = await init(args);
-
-    const { fusion } = args;
-
-    modules.event.dispatchEvent('onReactAppLoaded', {
-      detail: { modules, fusion, env: args.env },
-      source: Component,
-    });
-
-    return {
-      default: () => (
-        <FrameworkProvider value={fusion}>
-          <AppModuleProvider value={modules}>{Component}</AppModuleProvider>
-        </FrameworkProvider>
-      ),
-    };
-  });
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    onReactAppLoaded: FrameworkEvent<
-      FrameworkEventInit<
-        { modules: AppModulesInstance; fusion: Fusion; env: AppEnv },
-        React.ComponentType
-      >
-    >;
-  }
-}
-
-export default makeComponent;

package/src/msal/index.ts

@@ -1,16 +0,0 @@
-/**
- * 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,26 +0,0 @@
-import { useToken } from './useToken';
-
-/**
- * React hook that acquires an OAuth 2.0 access token string via MSAL.
- *
- * 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[];
-}): { token?: string; pending: boolean; error: unknown } => {
-  const { token, error, pending } = useToken(req);
-  return { token: token?.accessToken, pending, error };
-};

package/src/msal/useCurrentAccount.ts

@@ -1,21 +0,0 @@
-import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
-import useAppModule from '../useAppModule';
-
-/**
- * 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');
-  return msalProvider.account || undefined;
-};

package/src/msal/useToken.ts

@@ -1,52 +0,0 @@
-import { useEffect, useState } from 'react';
-
-import type { AuthenticationResult } from '@equinor/fusion-framework-module-msal';
-
-import useAppModule from '../useAppModule';
-
-/**
- * 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[];
-}): { token?: AuthenticationResult; pending: boolean; error: unknown } => {
-  const msalProvider = useAppModule('auth');
-  const [token, setToken] = useState<AuthenticationResult | undefined>(undefined);
-  const [pending, setPending] = useState<boolean>(false);
-  const [error, setError] = useState<unknown>(null);
-  useEffect(() => {
-    setPending(true);
-    setToken(undefined);
-    msalProvider
-      .acquireToken({ request: req })
-      .then((result) => {
-        // Only update state when a token was actually acquired
-        if (result) {
-          setToken(result);
-        }
-      })
-      .catch(setError)
-      .finally(() => setPending(false));
-  }, [msalProvider, req]);
-  return { token, pending, error };
-};
-
-export default useToken;

package/src/navigation/index.ts

@@ -1,10 +0,0 @@
-/**
- * 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,10 +0,0 @@
-import useAppModule from '../useAppModule';
-import type { INavigationProvider } from '@equinor/fusion-framework-module-navigation';
-
-/**
- * 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

@@ -1,35 +0,0 @@
-import { useMemo } from 'react';
-import { useNavigationModule } from './useNavigationModule';
-import type { INavigationProvider } from '@equinor/fusion-framework-module-navigation';
-
-/**
- * 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 '@equinor/fusion-framework-react-router';
- *
- * const routes = [{ path: '/', element: <Home /> }];
- * const App = () => {
- *   const router = useRouter(routes);
- *   return <RouterProvider router={router} />;
- * };
- * ```
- */
-export const useRouter = (
-  routes: Parameters<INavigationProvider['createRouter']>[0],
-): ReturnType<INavigationProvider['createRouter']> => {
-  const provider = useNavigationModule();
-  return useMemo(() => provider.createRouter(routes), [provider, routes]);
-};

package/src/render-app.ts

@@ -1,35 +0,0 @@
-import { createComponent } from './create-component';
-import { renderComponent, type RenderTeardown } from './render-component';
-
-import type { ComponentRenderArgs } from './create-component';
-
-/**
- * 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 => {
-    return renderer(el, args);
-  };
-};
-
-export default renderApp;

package/src/render-component.tsx

@@ -1,55 +0,0 @@
-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';
-
-/**
- * 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.
- *
- * 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);
-  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/routing/index.ts

@@ -1,33 +0,0 @@
-/**
- * Routing sub-path entry-point for `@equinor/fusion-framework-react-app`.
- *
- * Re-exports the full public API of `@equinor/fusion-framework-react-router`
- * and its route builder DSL so consumers can import all routing primitives
- * from a single entry point without adding a separate direct dependency.
- *
- * Requires `@equinor/fusion-framework-react-router` to be installed.
- * It is declared as an optional peer dependency — install it only when
- * you need routing in your app, portal, or widget.
- *
- * @example
- * ```ts
- * import { Router } from '@equinor/fusion-framework-react-app/routing';
- * import { layout, index, route } from '@equinor/fusion-framework-react-app/routing';
- * ```
- *
- * @packageDocumentation
- */
-export * from '@equinor/fusion-framework-react-router';
-// Explicit re-exports from /routes so the DSL `Route` class takes precedence
-// over the deprecated react-router `Route` component from the main entry.
-export {
-  index,
-  IndexRoute,
-  route,
-  Route,
-  layout,
-  LayoutRoute,
-  prefix,
-  PrefixRoute,
-} from '@equinor/fusion-framework-react-router/routes';
-export type { RouteSchemaEntry } from '@equinor/fusion-framework-react-router/routes';