@equinor/fusion-framework-react 9.0.0-next.0 → 9.0.1

package/src/Framework.tsx

@@ -1,68 +0,0 @@
-import type { FrameworkConfigurator } from '@equinor/fusion-framework';
-import { createFrameworkProvider } from './create-framework-provider';
-import { type PropsWithChildren, type ReactNode, Suspense, useMemo } from 'react';
-import { useModules } from '@equinor/fusion-framework-react-module';
-import type { ModulesInstance } from '@equinor/fusion-framework-module';
-
-/**
- * Callback invoked during framework initialisation to configure modules.
- *
- * @param configurator - The framework configurator instance to apply settings to.
- */
-type ConfigureCallback = (configurator: FrameworkConfigurator) => void;
-
-/**
- * Declarative React component that initialises a Fusion Framework instance
- * and provides it to descendant components via context.
- *
- * @remarks
- * Internally calls {@link createFrameworkProvider} and wraps the lazy-loaded
- * provider in a `<Suspense>` boundary. This is the recommended high-level
- * component for portal / host applications that need to bootstrap the
- * framework inside a React tree.
- *
- * @param props.configure - Callback that receives a {@link FrameworkConfigurator}
- *   for registering modules and configuration.
- * @param props.fallback - React node shown while the framework is initialising.
- * @param props.parent - Optional parent module instance to inherit configuration from.
- * @param props.children - Application content rendered after initialisation.
- *
- * @example
- * ```tsx
- * import { Framework } from '@equinor/fusion-framework-react';
- *
- * const App = () => (
- *   <Framework
- *     configure={(configurator) => {
- *       configurator.http.configureClient('my-api', { baseUri: 'https://api.example.com' });
- *     }}
- *     fallback={<span>Loading…</span>}
- *   >
- *     <MyApp />
- *   </Framework>
- * );
- * ```
- */
-export const Framework = (
-  props: PropsWithChildren<{
-    readonly configure: ConfigureCallback;
-    readonly fallback: NonNullable<ReactNode> | null;
-    // biome-ignore lint/suspicious/noExplicitAny: should allow any
-    readonly parent?: ModulesInstance<any>;
-  }>,
-) => {
-  const { configure, fallback, parent, children } = props;
-  //import modules from parent context
-  const ref = useModules<[]>();
-  const Component = useMemo(
-    () => createFrameworkProvider(configure, parent ?? ref),
-    [configure, ref, parent],
-  );
-  return (
-    <Suspense fallback={fallback}>
-      <Component>{children}</Component>
-    </Suspense>
-  );
-};
-
-export default Framework;

package/src/app/index.ts

@@ -1,17 +0,0 @@
-/**
- * Application React hooks.
- *
- * @remarks
- * Available via the `@equinor/fusion-framework-react/app` sub-entry-point.
- * Provides hooks and types for querying application manifests, observing
- * the currently active app, and accessing app-level modules.
- *
- * @module
- */
-export type { AppConfig, AppManifest, AppType, IApp } from '@equinor/fusion-framework-module-app';
-
-export { useCurrentApp } from './useCurrentApp';
-export { useCurrentAppModule } from './useCurrentAppModule';
-export { useCurrentAppModules } from './useCurrentAppModules';
-export { useApps } from './useApps';
-export { useAppProvider } from './useAppProvider';

package/src/app/useAppProvider.ts

@@ -1,29 +0,0 @@
-import type { FusionModulesInstance } from '@equinor/fusion-framework';
-import type { AppModule } from '@equinor/fusion-framework-module-app';
-
-import { useFramework } from '../useFramework';
-
-/**
- * React hook that returns the App module provider from the framework.
- *
- * @returns The app module instance (`AppModule`) for querying and managing
- *   application manifests and the currently active app.
- * @throws {Error} If the `AppModule` is not configured in the framework.
- *
- * @example
- * ```ts
- * const provider = useAppProvider();
- * provider.getAppManifests().subscribe(console.log);
- * ```
- */
-export const useAppProvider = (): FusionModulesInstance<[AppModule]>['app'] => {
-  const provider = useFramework<[AppModule]>().modules.app;
-  // Fail fast when the AppModule has not been configured on the framework
-  if (!provider) {
-    throw Error('Current framework does not have AppModule configured');
-  }
-
-  return provider;
-};
-
-export default useAppProvider;

package/src/app/useApps.ts

@@ -1,55 +0,0 @@
-import type { AppManifest } from '@equinor/fusion-framework-module-app';
-import { useObservableState } from '@equinor/fusion-observable/react';
-import { useMemo } from 'react';
-
-import { useAppProvider } from './useAppProvider';
-
-type UseAppsArgs = {
-  /** @deprecated - no longer available */
-  includeHidden?: boolean;
-  // only show apps that the current user has access to
-  filterByCurrentUser?: boolean;
-};
-
-/**
- * React hook that retrieves available application manifests from the framework.
- *
- * @param args - Optional filtering options.
- * @param args.filterByCurrentUser - When `true`, only apps accessible to the
- *   current user are returned.
- * @returns An object containing:
- *   - `apps` — Array of {@link AppManifest} objects, or `undefined` while loading.
- *   - `isLoading` — `true` until the observable completes.
- *   - `error` — Any error emitted by the underlying observable.
- *
- * @example
- * ```tsx
- * const { apps, isLoading, error } = useApps({ filterByCurrentUser: true });
- * if (isLoading) return <Spinner />;
- * return <AppList apps={apps} />;
- * ```
- *
- * @since 7.1.1
- */
-export const useApps = (
-  args?: UseAppsArgs,
-): { apps: AppManifest[] | undefined; isLoading: boolean; error: unknown } => {
-  const provider = useAppProvider();
-
-  const { filterByCurrentUser } = args || {};
-
-  const {
-    value: apps,
-    complete,
-    error,
-  } = useObservableState(
-    useMemo(
-      () => provider.getAppManifests(filterByCurrentUser ? { filterByCurrentUser } : undefined),
-      [provider, filterByCurrentUser],
-    ),
-  );
-
-  return { apps: apps as AppManifest[] | undefined, isLoading: !complete, error };
-};
-
-export default useApps;

package/src/app/useCurrentApp.ts

@@ -1,67 +0,0 @@
-import { useMemo } from 'react';
-
-import { useObservableState } from '@equinor/fusion-observable/react';
-
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import type {
-  ConfigEnvironment,
-  AppModule,
-  CurrentApp,
-} from '@equinor/fusion-framework-module-app';
-
-import { useFramework } from '../useFramework';
-
-/**
- * React hook that observes and returns the currently active application.
- *
- * @remarks
- * Subscribes to the `current$` stream on the App module and returns the
- * latest value together with helpers to change or clear the active app.
- *
- * **Warning:** The template parameters are compile-time hints only — the
- * hook does not validate that the specified modules are actually enabled.
- *
- * @template TModules - Tuple of module types the current app is expected to
- *   have configured (type-hint only).
- * @template TEnv - Expected environment configuration shape (type-hint only).
- *
- * @returns An object containing:
- *   - `currentApp` — The current {@link CurrentApp} instance, `null` when
- *     explicitly cleared, or `undefined` while loading.
- *   - `setCurrentApp(appKey)` — Sets the active app by its key.
- *   - `clearCurrentApp()` — Clears the currently active app.
- *   - `error` — Any error emitted by the observable.
- *
- * @throws {Error} If the `AppModule` is not configured in the framework.
- *
- * @example
- * ```tsx
- * const { currentApp, setCurrentApp } = useCurrentApp();
- * return <button onClick={() => setCurrentApp('my-app')}>{currentApp?.manifest?.name}</button>;
- * ```
- */
-export const useCurrentApp = <
-  TModules extends Array<AnyModule> = [],
-  TEnv extends ConfigEnvironment = ConfigEnvironment,
->(): {
-  currentApp?: CurrentApp<TModules, TEnv> | null;
-  setCurrentApp: (appKey: string) => void;
-  clearCurrentApp: () => void;
-  error?: unknown;
-} => {
-  const provider = useFramework<[AppModule]>().modules.app;
-  // Fail fast when the AppModule has not been configured on the framework
-  if (!provider) {
-    throw Error('Current framework does not have AppModule configured');
-  }
-  const currentApp$ = useMemo(() => provider.current$, [provider]);
-  const { value, error } = useObservableState(currentApp$, { initial: provider.current });
-  return {
-    currentApp: value as CurrentApp<TModules, TEnv>,
-    setCurrentApp: useMemo(() => provider.setCurrentApp.bind(provider), [provider]),
-    clearCurrentApp: useMemo(() => provider.clearCurrentApp.bind(provider), [provider]),
-    error,
-  };
-};
-
-export default useCurrentApp;

package/src/app/useCurrentAppModule.ts

@@ -1,57 +0,0 @@
-import type { AppModules, AppModulesInstance } from '@equinor/fusion-framework-module-app';
-import type {
-  ModuleKey,
-  AnyModule,
-  ModuleTypes,
-  ModuleType,
-} from '@equinor/fusion-framework-module';
-import useCurrentAppModules from './useCurrentAppModules';
-
-/**
- * React hook that retrieves a specific module from the current application.
- *
- * @template TType - The expected module type.
- * @template TKey - The module key used for look-up.
- * @param moduleKey - The key of the module to retrieve.
- * @returns An object containing:
- *   - `module` — The resolved module instance, `null` when no app is
- *     selected, or `undefined` if the app does not enable the requested module.
- *   - `error` — Any error emitted during initialisation.
- *   - `complete` — `true` when the observable has completed.
- *
- * @remarks
- * - A `null` value means no application is currently selected.
- * - An `undefined` value means the application has not enabled the requested module.
- */
-export const useCurrentAppModule = <
-  TType extends AnyModule | unknown = unknown,
-  TKey extends string = ModuleKey<ModuleTypes<AppModules<[TType]>>>,
->(
-  moduleKey: TKey,
-): {
-  module?:
-    | (TType extends AnyModule
-        ? ModuleType<TType>
-        : AppModulesInstance[Extract<keyof AppModulesInstance, TKey>])
-    | null;
-  error?: unknown;
-  complete: boolean;
-} => {
-  const { modules, error, complete } = useCurrentAppModules();
-  const module = (() => {
-    // Preserve an explicit null (modules not applicable) distinct from undefined (not yet loaded)
-    if (modules === null) {
-      return null;
-    }
-    // Modules are still loading; propagate undefined rather than throwing
-    if (modules === undefined) {
-      return undefined;
-    }
-    // Module lookup by dynamic key can't be statically narrowed to the exact module type; cast to any.
-    // biome-ignore lint/suspicious/noExplicitAny: dynamic key lookup can't be statically narrowed to the exact module type
-    return modules[moduleKey as keyof typeof modules] as any;
-  })();
-  return { module, error, complete };
-};
-
-export default useCurrentAppModule;

package/src/app/useCurrentAppModules.ts

@@ -1,52 +0,0 @@
-import { useMemo } from 'react';
-import useCurrentApp from './useCurrentApp';
-
-import type { AppModulesInstance } from '@equinor/fusion-framework-module-app';
-import { type Observable, of } from 'rxjs';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import { useObservableState } from '@equinor/fusion-observable/react';
-
-/**
- * React hook that observes the initialised modules of the current application.
- *
- * @remarks
- * Subscribes to the `instance$` stream of the current app and returns the
- * resolved module instances.
- *
- * **Warning:** The template parameter is a compile-time hint only — the
- * hook does not validate that the specified modules are actually enabled.
- *
- * @template TModules - Tuple of module types expected on the current app
- *   (type-hint only).
- * @returns An object containing:
- *   - `modules` — The initialised {@link AppModulesInstance}, `null` when no
- *     app is selected, or `undefined` while loading.
- *   - `error` — Any error emitted during initialisation.
- *   - `complete` — `true` when the observable has completed.
- */
-export const useCurrentAppModules = <TModules extends Array<AnyModule> = []>(): {
-  modules?: AppModulesInstance<TModules> | null;
-  error?: unknown;
-  complete: boolean;
-} => {
-  const { currentApp, error: appError } = useCurrentApp<TModules>();
-  const modules$ = useMemo(
-    () =>
-      currentApp ? (currentApp.instance$ as Observable<AppModulesInstance<TModules>>) : of(null),
-    [currentApp],
-  );
-  const {
-    value: modules,
-    error,
-    complete,
-  } = useObservableState(modules$, {
-    initial: currentApp === undefined ? undefined : (currentApp?.instance ?? null),
-  });
-  return {
-    modules,
-    error: error ?? appError,
-    complete,
-  };
-};
-
-export default useCurrentAppModules;

package/src/context/index.ts

@@ -1,13 +0,0 @@
-/**
- * Context React hooks.
- *
- * @remarks
- * Available via the `@equinor/fusion-framework-react/context` sub-entry-point.
- * Re-exports the context module’s React API and adds a convenience
- * `useCurrentContext` hook that resolves the module from the framework.
- *
- * @module
- */
-export * from '@equinor/fusion-framework-react-module-context';
-
-export { useCurrentContext } from './useCurrentContext';

package/src/context/useCurrentContext.ts

@@ -1,22 +0,0 @@
-import { useCurrentContext as _useCurrentContext } from '@equinor/fusion-framework-react-module-context';
-import { useFramework } from '../useFramework';
-
-/**
- * React hook that returns the currently selected Fusion context.
- *
- * @remarks
- * This is a convenience wrapper that resolves the context module from the
- * framework instance and delegates to the underlying
- * `useCurrentContext` hook from `@equinor/fusion-framework-react-module-context`.
- *
- * @returns The current context state as defined by the context module.
- *
- * @example
- * ```ts
- * const { currentContext } = useCurrentContext();
- * console.log(currentContext?.id);
- * ```
- */
-export const useCurrentContext = () => _useCurrentContext(useFramework().modules.context);
-
-export default useCurrentContext;

package/src/context.ts

@@ -1,14 +0,0 @@
-import { createContext } from 'react';
-import type { Fusion } from '@equinor/fusion-framework';
-
-/**
- * Internal React context that holds the current {@link Fusion} instance.
- *
- * @remarks
- * Consumers should not use this directly — prefer the {@link useFramework}
- * hook or the {@link FrameworkProvider} component.
- *
- * @internal
- */
-// biome-ignore lint/suspicious/noExplicitAny: `Fusion<any>` widens the context to accept a Fusion instance with any concrete module set
-export const context = createContext<Fusion<any> | null>(null);

package/src/create-framework-provider.tsx

@@ -1,69 +0,0 @@
-import type React from 'react';
-import { lazy } from 'react';
-import initFusion from '@equinor/fusion-framework';
-import { FrameworkConfigurator } from '@equinor/fusion-framework';
-
-import { FrameworkProvider } from './framework-provider';
-import type { AnyModule, ModulesInstanceType } from '@equinor/fusion-framework-module';
-import { ModuleProvider } from '@equinor/fusion-framework-react-module';
-
-/**
- * Creates a lazy-loaded React component that initialises a Fusion Framework
- * instance and exposes it via context providers.
- *
- * @remarks
- * This is the low-level factory used by the {@link Framework} component.
- * Call it when you need fine-grained control over memoisation or when you
- * want to embed the provider in a custom `<Suspense>` boundary.
- *
- * The returned component is created with `React.lazy`, so it **must** be
- * rendered inside a `<Suspense>` boundary.
- *
- * @template TModules - Tuple of additional module types to register.
- * @template TRef - Type of the optional parent module-instance reference.
- *
- * @param cb - Callback that receives a {@link FrameworkConfigurator} (and an
- *   optional parent ref) for registering modules and configuration.
- * @param ref - Optional parent module instance to inherit configuration from.
- * @returns A `React.lazy` component that provides the initialised framework
- *   to its children.
- *
- * @example
- * ```tsx
- * import { createFrameworkProvider } from '@equinor/fusion-framework-react';
- *
- * const Portal = () => {
- *   const FrameworkProvider = createFrameworkProvider((config) => {
- *     config.http.configureClient('my-api', { baseUri: 'https://api.example.com' });
- *   });
- *
- *   return (
- *     <Suspense fallback={<span>Loading…</span>}>
- *       <FrameworkProvider>
- *         <App />
- *       </FrameworkProvider>
- *     </Suspense>
- *   );
- * };
- * ```
- */
-export const createFrameworkProvider = <
-  TModules extends Array<AnyModule> = [],
-  // biome-ignore lint/suspicious/noExplicitAny: default must be bivariant `any`, not `unknown` \u2014 `unknown` breaks assignability when a concrete `TRef` is passed where the default-typed generic is expected
-  TRef extends ModulesInstanceType<[AnyModule]> = any,
->(
-  cb: (configurator: FrameworkConfigurator<TModules>, ref?: TRef) => void | Promise<void>,
-  ref?: TRef,
-): React.LazyExoticComponent<React.FunctionComponent<React.PropsWithChildren<unknown>>> =>
-  lazy(async () => {
-    const configurator = new FrameworkConfigurator<TModules>();
-    await cb(configurator, ref);
-    const framework = await initFusion(configurator, ref);
-    return {
-      default: ({ children }: { children?: React.ReactNode }) => (
-        <FrameworkProvider value={framework}>
-          <ModuleProvider value={framework.modules}>{children}</ModuleProvider>
-        </FrameworkProvider>
-      ),
-    };
-  });

package/src/feature-flag/README.md

@@ -1,44 +0,0 @@
-__useCurrentAppFeatures__
-
-Custom hook for accessing all feature flags for an application
-
-```tsx
-const Component =  () => {
-  const appFeatures = useCurrentAppFeatures();
-  if( appFeatures.features === undefined ){
-      return <p>The current app does not have features enabled</p>
-  }
-  return (
-    <>
-      { 
-        appFeatures.features.map(feature => (
-          <button
-            key={feature.key}
-            disabled={ appFeatures.readOnly }
-            onClick={ () => appFeatures.toggleFeature( feature.key ) }
-          >
-            { feature.enabled ? 'disable' : 'enable' } feature { feature.title }
-          </button>
-        )) 
-      
-      }
-    </>
-  )
-}
-```
-
-__useFrameworkFeature__
-
-Custom hook for using a framework feature
-
-__useFrameworkFeatures__
-
-Custom hook for using all framework features
-
-__useFeature__
-
-> internal hook for getting a feature from a feature flag module
-
-__useFeatures__
-
-> internal hook for getting features of a feature flag module

package/src/feature-flag/index.ts

@@ -1,17 +0,0 @@
-/**
- * Feature-flag React hooks.
- *
- * @remarks
- * Available via the `@equinor/fusion-framework-react/feature-flag` sub-entry-point.
- * Provides hooks to read, toggle, and observe feature flags at the
- * framework or application level.
- *
- * @module
- */
-export { useFeature } from './useFeature';
-export { useFeatures } from './useFeatures';
-export { useCurrentAppFeatures } from './useCurrentAppFeatures';
-export { useFrameworkFeature } from './useFrameworkFeature';
-export { useFrameworkFeatures } from './useFrameworkFeatures';
-
-export { IFeatureFlag, IFeatureFlagProvider } from '@equinor/fusion-framework-module-feature-flag';

package/src/feature-flag/useCurrentAppFeatures.ts

@@ -1,29 +0,0 @@
-import type { FeatureFlagModule } from '@equinor/fusion-framework-module-feature-flag';
-import { useCurrentAppModule } from '../app';
-import { useFeatures, type UseFeaturesResult } from './useFeatures';
-
-/**
- * React hook that returns feature flags registered on the current application.
- *
- * @returns A {@link UseFeaturesResult} containing:
- *   - `features` — Array of feature flags for the current app.
- *   - `toggleFeature(key, enable?)` — Toggles a feature flag on or off.
- *   - `error` — Any error from the feature-flag or app-module streams.
- *
- * @example
- * ```ts
- * const { features, toggleFeature } = useCurrentAppFeatures();
- * toggleFeature('dark-mode', true);
- * ```
- */
-export const useCurrentAppFeatures = (): UseFeaturesResult => {
-  const { module, error: moduleError } = useCurrentAppModule<FeatureFlagModule>('featureFlag');
-
-  const { features, toggleFeature, error } = useFeatures(module);
-
-  return {
-    features,
-    toggleFeature,
-    error: error ?? moduleError,
-  };
-};

package/src/feature-flag/useFeature.ts

@@ -1,71 +0,0 @@
-import { useCallback, useMemo } from 'react';
-
-import { EMPTY } from 'rxjs';
-
-import type {
-  IFeatureFlag,
-  IFeatureFlagProvider,
-} from '@equinor/fusion-framework-module-feature-flag';
-
-import { useObservableState } from '@equinor/fusion-observable/react';
-
-import { findFeature } from '@equinor/fusion-framework-module-feature-flag/selectors';
-
-/**
- * Return type of the {@link useFeature} hook.
- *
- * @template T - Value type carried by the feature flag.
- */
-export interface UseFeatureResult<T> {
-  /** The resolved feature flag, or `undefined` while loading. */
-  feature?: IFeatureFlag<T>;
-  /** Any error emitted by the feature-flag observable. */
-  error?: unknown;
-  /**
-   * Toggles the feature flag.
-   *
-   * @param enable - Explicit enabled state. When omitted the current state
-   *   is inverted.
-   */
-  toggleFeature: (enable?: boolean) => void;
-}
-
-/**
- * React hook that retrieves and manages a single feature flag.
- *
- * @template T - Value type carried by the feature flag.
- * @param provider - The feature-flag provider instance.
- * @param key - Unique key identifying the feature flag.
- * @returns A {@link UseFeatureResult} with the flag value, toggle helper,
- *   and any error.
- *
- * @example
- * ```ts
- * const { feature, toggleFeature } = useFeature(provider, 'dark-mode');
- * console.log(feature?.enabled);
- * ```
- */
-export const useFeature = <T = unknown>(
-  provider: IFeatureFlagProvider,
-  key: string,
-): UseFeatureResult<T> => {
-  // Narrow the features stream down to just the one matching feature by key.
-  const feature$ = useMemo(
-    () =>
-      provider.features$
-        // Keep the observable scoped to the requested feature key.
-        .pipe(findFeature<T>(key)),
-    [provider, key],
-  );
-  const { value: feature, error } = useObservableState(feature$ ?? EMPTY);
-  const toggleFeature = useCallback(
-    (enable?: boolean) => {
-      const enabled = enable === undefined ? !provider.getFeature(key)?.enabled : enable;
-      provider.toggleFeature({ key, enabled });
-    },
-    [provider, key],
-  );
-  return { feature, toggleFeature, error };
-};
-
-export default useFeature;