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

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,63 +0,0 @@
-import { useEffect, useRef, 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);
-
-  // `req` is typically a fresh object literal each render; key the effect on its
-  // scopes' content instead of identity, so it doesn't re-run (and reset `pending`
-  // to `true` forever) every time the caller re-renders. `JSON.stringify` (rather than
-  // `.join(',')`) keeps scopes with different array boundaries (e.g. `['a,b']` vs.
-  // `['a', 'b']`) from colliding on the same key.
-  const scopesKey = JSON.stringify(req.scopes);
-  const reqRef = useRef(req);
-  reqRef.current = req;
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: scopesKey is a re-run trigger, not read in the body
-  useEffect(() => {
-    setPending(true);
-    setToken(undefined);
-    msalProvider
-      .acquireToken({ request: reqRef.current })
-      .then((result) => {
-        // Only update state when a token was actually acquired
-        if (result) {
-          setToken(result);
-        }
-      })
-      .catch(setError)
-      .finally(() => setPending(false));
-  }, [msalProvider, scopesKey]);
-  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';

package/src/settings/README.md

@@ -1,123 +0,0 @@
-## Portal Settings
-
-> TBD
-
-## App Settings
-
-App settings are a way to store and retrieve settings that are shared across the app. The settings are stored in the configured service of the app module.
-
-```ts
-declare module '@equinor/fusion-framework-react-app/settings' {
-  interface AppSettings {
-    theme: 'default' | 'light' | 'dark';
-    mode: 'simple' | 'advanced';
-  }
-}
-useAppSetting('theme', 'default');
-
-// Explicit type the setting
-useAppSetting<{notDefined: string}>('notDefined', 'not registered');
-```
-
-### Example
-
-```tsx
-const MyApp = () => {
-  const [ theme, setTheme ] = useAppSetting('theme', 'default');
-  const [ mode, setMode ] = useAppSetting('mode', 'simple');
-
-  // using the setter as a callback
-  const toggleMode = useCallback(() => {
-    setMode(mode => mode === 'simple' ? 'advanced' : 'simple')
-  }, [setMode]);
-
-  return (
-    <MyThemeProvider theme={theme} onChange={setTheme}>
-      <Button onClick={toggleMode}>Toggle mode</Button>
-      {mode === 'simple' ? <SimpleView /> : <AdvancedView />}
-    </MyThemeProvider>
-  );
-}
-```
-
-### Using all settings
-
-> [!WARNING]
-> **Using the `setSettings` must include all settings, not just the ones you want to change.**
-> prefer using `setSettings` with a callback function.
-
-> [!IMPORTANT]
-> This is not recommended for large apps, as it will cause re-renders on every setting change.
-
-```tsx
-const MyApp = () => {
-  const [ settings, setSettings ] = useAppSettings();
-
-  const updateTheme = useCallback(
-    (theme: AppSettings['theme']) => setSettings(settings => ({...settings, theme})),
-    [updateSettings]
-  );
-      
-  return (
-    <MyThemeProvider theme={settings.theme} onChange={updateTheme}>
-      {settings.mode === 'simple' ? <SimpleView /> : <AdvancedView />}
-    </MyThemeProvider>
-  );
-}
-```
-
-### Using hook callbacks
-
-The `useAppSettings` and `useAppSetting` hooks can take callbacks for loading, updating, updated and error handling.
-
-> [!NOTE]
-> These callbacks are optional and can be used to show loading spinners, error dialogs or other UI elements.
->
-> We have chosen to use callbacks as parameters to the hooks, instead of returning them, to avoid unnecessary re-renders.
-
-> [!NOTE]
-> `onUpdating` and `onLoading` refers to the global state of the settings, not the individual settings. This means that if you have multiple settings that are being updated, the `onUpdating` and `onLoading` will be true until all settings are updated.
-> 
-> Good practice is to disable UI elements that can trigger settings updates when `onUpdating` or `onLoading` is true.
-
-
-> [!IMPORTANT]
-> Hooks must be memoized to avoid re-renders on every render. Provided callbacks are not internally memoized, to allow consumers to control implementation of these callbacks.
-
-```tsx
-
-// state and callback for loading settings
-const [ loading, setLoading ] = useState(false);
-
-// state and callback for updating settings
-const [ updating, setUpdating ] = useState(false);
-
-// state and callback for error handling
-const [ error, setError ] = useState<Error | null>(null);
-
-// callback for when settings are updated
-const onUpdated = useCallback(() => {
-  showSnackbar('Settings updated');
-}, [showSnackbar]);
-
-const [ settings, setSettings ] = useAppSettings(defaultSettings, {
-  onLoading: setLoading,
-  onUpdating: setUpdating,
-  onError: setError,
-});
-
-const updateSettings = useCallback(() => {
-  setSettings(/* new settings */);
-}, [setSettings, onUpdated]);
-
-return (
-  <MyThemeProvider theme={settings.theme}>
-    {loading && <Loading />}
-    {updating && <Updating />}
-    {error && <ErrorDialog error={error} />}
-    <Button onClick={updateSettings} disabled={loading||updating}>
-      Update settings
-    </Button>
-  </MyThemeProvider>
-);
-```

package/src/settings/index.ts

@@ -1,12 +0,0 @@
-/**
- * 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';
-
-export type { AppSettings } from '@equinor/fusion-framework-module-app';

package/src/settings/useAppSetting.ts

@@ -1,113 +0,0 @@
-import { useCallback, useLayoutEffect, useMemo, useState } from 'react';
-import { BehaviorSubject, map } from 'rxjs';
-
-import { useCurrentApp } from '@equinor/fusion-framework-react/app';
-
-import { useAppSettingsStatus, type AppSettingsStatusHooks } from './useAppSettingsStatus';
-
-import type { AppSettings } from '@equinor/fusion-framework-module-app';
-import { useObservableState } from '@equinor/fusion-observable/react';
-
-type UpdateSettingFunction<T, O = T> = (currentSetting: T | undefined) => O;
-
-/**
- * Custom hook to manage application settings.
- *
- * @template TSettings - The type of the settings object. Defaults to `AppSettings`.
- * @template TProp - The type of the property key in the settings object. Defaults to `keyof TSettings`.
- *
- * @param {TProp} prop - The property key in the settings object to manage.
- * @param {TSettings[TProp]} [defaultValue] - The default value for the setting.
- * @param hooks - Optional hooks to handle the status changes and errors.
- *
- * @returns {Array} An array containing:
- * - `setting`: The current setting value or undefined.
- * - `setSetting`: A function to update the setting.
- *
- * @example
- * const { setting, setSetting } = useAppSetting('theme');
- *
- * @example
- * // with default value
- * const { setting, setSetting } = useAppSetting('theme', 'dark');
- *
- * @example
- * // with hooks
- * const [isLoading, setIsLoading] = useState(false);
- * const [isUpdating, setIsUpdating] = useState(false);
- * const [error, setError] = useState<Error | null>(null);
- *
- * const { setting, setSetting } = useAppSetting('theme', 'dark', {
- *    onLoading: setIsLoading,
- *    onUpdating: setIsUpdating,
- *    onError: setError,
- *    onUpdated: useCallback(() => console.log('Settings updated'), [])
- * });
- */
-export const useAppSetting = <
-  TSettings extends Record<string, unknown> = AppSettings,
-  TProp extends keyof TSettings = keyof TSettings,
->(
-  prop: TProp,
-  defaultValue?: TSettings[TProp],
-  hooks?: AppSettingsStatusHooks & {
-    onError?: (error: Error | null) => void;
-    onUpdated?: () => void;
-  },
-): [
-  TSettings[TProp] | undefined,
-  (update: TSettings[TProp] | UpdateSettingFunction<TSettings[TProp]>) => void,
-] => {
-  const [{ onError, onUpdated, onLoading, onUpdating }] = useState(() => hooks ?? {});
-
-  const { currentApp = null } = useCurrentApp();
-
-  // create a subject to manage the setting value
-  // biome-ignore lint/correctness/useExhaustiveDependencies: new subject when app changes
-  const subject = useMemo(() => {
-    return new BehaviorSubject<TSettings[TProp] | undefined>(defaultValue);
-  }, [currentApp]);
-
-  useLayoutEffect(() => {
-    // Narrow the settings stream down to just this specific setting's value
-    const sub = currentApp?.settings$
-      .pipe(map((settings) => (settings as TSettings)[prop]))
-      .subscribe(subject);
-    return () => sub?.unsubscribe();
-  }, [currentApp, subject, prop]);
-
-  // subscribe to the setting value
-  const { value: setting } = useObservableState(subject);
-
-  // update function
-  const setSetting = useCallback(
-    (update: TSettings[TProp] | UpdateSettingFunction<TSettings[TProp]>) => {
-      // Cannot persist a setting update without a current app to write it to
-      if (!currentApp) {
-        return onError?.(new Error('App is not available'));
-      }
-
-      // resolve setting value with the provided value or function
-      const value =
-        typeof update === 'function'
-          ? (update as UpdateSettingFunction<TSettings[TProp]>)(subject.value)
-          : update;
-
-      currentApp.updateSetting<TSettings, TProp>(prop, value).subscribe({
-        error: onError,
-        complete: onUpdated,
-      });
-    },
-    [currentApp, subject, prop, onError, onUpdated],
-  );
-
-  // status hooks
-  useAppSettingsStatus(currentApp, {
-    onLoading,
-    onUpdating,
-  });
-
-  return [setting, setSetting];
-};
-
-export default useAppSetting;