@equinor/fusion-framework-react 8.0.0-next.0 → 8.0.1

package/src/feature-flag/useFeatures.ts

@@ -12,23 +12,40 @@ import type { FeatureSelectorFn } from '@equinor/fusion-framework-module-feature
 
 import { useObservableState } from '@equinor/fusion-observable/react';
 
+/**
+ * Return type of the {@link useFeatures} hook.
+ */
 export interface UseFeaturesResult {
+  /** Array of all resolved feature flags. */
   features: IFeatureFlag[];
+  /** Any error emitted by the feature-flag observable. */
   error: unknown;
   /**
+   * Toggles a feature flag by key.
+   *
    * @param key - The key of the feature flag.
-   * @param enable - Optional provide new enabled state of the feature flag. _Defaults to inversion of current feature flag state_
+   * @param enable - Explicit enabled state. When omitted the current state
+   *   is inverted.
    */
   toggleFeature: (key: string, enable?: boolean) => void;
 }
 
 /**
- * Custom hook that provides access to the feature flags and their values.
+ * React hook that returns all feature flags from a provider, with optional
+ * filtering.
+ *
+ * @param provider - The feature-flag provider instance, or `null`/`undefined`
+ *   when not yet available.
+ * @param selector - Optional predicate to filter the feature flags.
+ * @returns A {@link UseFeaturesResult} with the flags, a toggle helper,
+ *   and any error.
+ * @throws {Error} If `toggleFeature` is called when the provider is missing.
  *
- * @param provider - The feature flag provider.
- * @param selector - Optional function to filter the feature flags.
- * @returns An object containing the features, any error that occurred while retrieving them, and a function to set the enabled state of a feature flag.
- * @throws Error if the feature flag provider is missing.
+ * @example
+ * ```ts
+ * const { features, toggleFeature } = useFeatures(provider);
+ * toggleFeature('beta', true);
+ * ```
  */
 export const useFeatures = (
   provider?: IFeatureFlagProvider | null,
@@ -41,11 +58,19 @@ export const useFeatures = (
    */
   const { value: features, error } = useObservableState(
     useMemo(() => {
+      // Only compute the feature list when a provider is available; otherwise there's nothing to observe
       if (provider) {
+        // Map the feature dictionary to a list, optionally narrowed by the caller-provided selector
         return provider?.features$.pipe(
           map((x) => {
             const values = Object.values(x);
-            return selector ? values.filter(selector) : values;
+            // Return everything when no selector is provided
+            if (!selector) {
+              return values;
+            }
+            // Apply the caller-provided selector to narrow down the feature list
+            const filtered = values.filter(selector);
+            return filtered;
           }),
         );
       }
@@ -62,6 +87,7 @@ export const useFeatures = (
    */
   const toggleFeature = useCallback(
     (key: string, enable?: boolean) => {
+      // Cannot toggle a feature without a provider to persist the change
       if (!provider) {
         throw new Error('Missing IFeatureFlagProvider.');
       }

package/src/feature-flag/useFrameworkFeature.ts

@@ -4,15 +4,23 @@ import { useFrameworkModule } from '../useFrameworkModule';
 import { useFeature } from './useFeature';
 
 /**
- * Custom hook that allows accessing a framework feature based on a given feature flag key.
+ * React hook that retrieves a single feature flag from the **framework-level**
+ * feature-flag provider.
  *
- * @template T - The type of the feature.
- * @param {string} key - The feature flag key.
- * @returns {ReturnType<typeof useFeature<T>>} - The result of the feature hook.
- * @throws {Error} - If feature flagging is not enabled in the framework.
+ * @template T - Value type carried by the feature flag.
+ * @param key - Unique key identifying the feature flag.
+ * @returns A {@link UseFeatureResult} with the flag value, toggle helper,
+ *   and any error.
+ * @throws {Error} If the `FeatureFlagModule` is not enabled in the framework.
+ *
+ * @example
+ * ```ts
+ * const { feature, toggleFeature } = useFrameworkFeature('experimental-ui');
+ * ```
  */
 export const useFrameworkFeature = <T>(key: string): ReturnType<typeof useFeature<T>> => {
   const provider = useFrameworkModule<FeatureFlagModule>('featureFlag');
+  // Fail fast when the FeatureFlagModule has not been enabled on the framework
   if (!provider) {
     throw Error('Feature flagging is not enabled in the framework');
   }

package/src/feature-flag/useFrameworkFeatures.ts

@@ -4,13 +4,21 @@ import { useFrameworkModule } from '../useFrameworkModule';
 import { useFeatures } from './useFeatures';
 
 /**
- * Custom hook that provides access to framework-specific feature flags.
- * It returns the result of the `useFeatures` hook from the `featureFlag` module.
- * @returns The result of the `useFeatures` hook.
- * @throws Error if feature flagging is not enabled in the framework.
+ * React hook that returns all feature flags from the **framework-level**
+ * feature-flag provider.
+ *
+ * @returns A {@link UseFeaturesResult} containing all framework feature flags,
+ *   a toggle helper, and any error.
+ * @throws {Error} If the `FeatureFlagModule` is not enabled in the framework.
+ *
+ * @example
+ * ```ts
+ * const { features, toggleFeature } = useFrameworkFeatures();
+ * ```
  */
 export const useFrameworkFeatures = (): ReturnType<typeof useFeatures> => {
   const provider = useFrameworkModule<FeatureFlagModule>('featureFlag');
+  // Fail fast when the FeatureFlagModule has not been enabled on the framework
   if (!provider) {
     throw Error('Feature flagging is not enabled in the framework');
   }

package/src/framework-provider.ts

@@ -0,0 +1,21 @@
+import { context } from './context';
+
+/**
+ * Component for providing framework.
+ *
+ * @remarks
+ * Should be created by {@link createFrameworkProvider}
+ *
+ * @example
+ * ```tsx
+ * import {FrameworkProvider} from '@equinor/fusion-framework-react';
+ * export const Component = (args: React.PropsWithChildren<{framework: Fusion}>) => {
+ *   return (
+ *      <FrameworkProvider value={args.framework}>
+ *        {args.children}
+ *      </FrameworkProvider>
+ *   );
+ * }
+ * ```
+ */
+export const FrameworkProvider = context.Provider;

package/src/hooks/index.ts

@@ -1,2 +1,10 @@
-export { useCurrentUser } from './use-current-user';
-export { useHttpClient } from './use-http-client';
+/**
+ * Convenience hooks for common framework operations.
+ *
+ * @remarks
+ * Available via the `@equinor/fusion-framework-react/hooks` sub-entry-point.
+ *
+ * @module
+ */
+export { useCurrentUser } from './useCurrentUser';
+export { useHttpClient } from './useHttpClient';

package/src/hooks/useCurrentUser.ts

@@ -0,0 +1,21 @@
+import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
+import { useFramework } from '../useFramework';
+
+/**
+ * React hook that returns the currently authenticated user's account info.
+ *
+ * @returns The {@link AccountInfo} of the signed-in user, or `undefined` if
+ *   no user is authenticated.
+ *
+ * @example
+ * ```tsx
+ * const UserGreeting = () => {
+ *   const user = useCurrentUser();
+ *   return <span>Hello, {user?.name ?? 'Guest'}</span>;
+ * };
+ * ```
+ */
+export const useCurrentUser = (): AccountInfo | undefined => {
+  const framework = useFramework();
+  return framework.modules.auth.account || undefined;
+};

package/src/hooks/useHttpClient.ts

@@ -0,0 +1,36 @@
+import { useMemo } from 'react';
+import type { Fusion } from '@equinor/fusion-framework';
+import { useFramework } from '../useFramework';
+
+/** Resolved HTTP client instance returned by the framework HTTP module. */
+type HttpClient = ReturnType<Fusion['modules']['http']['createClient']>;
+
+/** Well-known HTTP client keys pre-configured by the framework. */
+type FrameworkHttpClient = 'portal' | 'people';
+
+/**
+ * React hook that returns a pre-configured HTTP client from the framework.
+ *
+ * @param name - Key of the HTTP client to retrieve (e.g. `'portal'` or `'people'`).
+ * @returns The resolved {@link HttpClient} instance.
+ * @throws {Error} If no client is configured for the given key.
+ *
+ * @example
+ * ```ts
+ * const client = useHttpClient('portal');
+ * client.fetch('/api/data').subscribe(console.log);
+ * ```
+ */
+export const useHttpClient = (name: FrameworkHttpClient): HttpClient => {
+  const framework = useFramework();
+
+  const client = useMemo(() => {
+    // Reuse an already-configured client for this key when one exists
+    if (framework.modules.http.hasClient(name)) {
+      return framework.modules.http.createClient(name);
+    }
+    throw Error(`no configured client for key [${name}]`);
+  }, [framework, name]);
+  // TODO(#5085): abort on unmount?
+  return client;
+};

package/src/http/index.ts

@@ -1,3 +1,13 @@
-export { useHttpClient as useFrameworkHttpClient } from '../hooks/use-http-client';
+/**
+ * HTTP sub-entry-point (`@equinor/fusion-framework-react/http`).
+ *
+ * @remarks
+ * Re-exports the framework-level {@link useHttpClient} hook as
+ * `useFrameworkHttpClient` together with all exports from the
+ * standalone HTTP React module.
+ *
+ * @module
+ */
+export { useHttpClient as useFrameworkHttpClient } from '../hooks/useHttpClient';
 
 export * from '@equinor/fusion-framework-react-module-http';

package/src/index.tsx

@@ -1,4 +1,12 @@
 /**
+ * React bindings for the Fusion Framework.
+ *
+ * @remarks
+ * This package provides React components, context providers, and hooks for
+ * initialising and consuming a Fusion Framework instance inside a React
+ * application tree. It is the main entry-point for portals and host
+ * applications that need to bootstrap the framework with React.
+ *
  * [[include:framework-react/README.MD]]
  * @module
  */
@@ -7,7 +15,7 @@ export type { Fusion } from '@equinor/fusion-framework';
 export { FusionConfigurator } from '@equinor/fusion-framework';
 
 export { createFrameworkProvider } from './create-framework-provider';
-export { FrameworkProvider } from './context';
+export { FrameworkProvider } from './framework-provider';
 
 export { useFramework } from './useFramework';
 export { useFrameworkModule } from './useFrameworkModule';

package/src/signalr/index.ts

@@ -1,39 +1 @@
-import { useFramework } from '../useFramework';
-
-import {
-  type SignalRModule,
-  useProviderTopic,
-} from '@equinor/fusion-framework-react-module-signalr';
-
-/**
- * hook for subscribing to a topic of a SignalR hub
- * 
- * @example
- ```ts
-// config.ts
-import {enableSignalR} from '@equinor/fusion-framework-react-module-signalr';
-(configurator) => enableSignalR(configurator, 'notifications');
-
-// myHook.ts
-const myHook = () => {
-    const topic = useSignalR('notifications', 'foo');
-    return useObservableState(topic).next;
-}
- ```
- *
- * @see {@link [module signalr](https://equinor.github.io/fusion-framework/modules/signalr)}
- *
- * @param hubId identifier of connection hub (must be configured)
- * @param topicId identifier of topic to connect to
- * @returns Topic
- */
-export const useSignalR = <T>(
-  hubId: string,
-  topicId: string,
-): ReturnType<typeof useProviderTopic<T>> => {
-  const provider = useFramework<[SignalRModule]>().modules.signalR;
-  if (!provider) {
-    throw Error('SignalR is not configured, see @equinor/fusion-framework-react-module-signalr');
-  }
-  return useProviderTopic(provider, hubId, topicId);
-};
+export { useSignalR } from './useSignalR.js';

package/src/signalr/useSignalR.ts

@@ -0,0 +1,40 @@
+import { useFramework } from '../useFramework';
+
+import {
+  type SignalRModule,
+  useProviderTopic,
+} from '@equinor/fusion-framework-react-module-signalr';
+
+/**
+ * hook for subscribing to a topic of a SignalR hub
+ * 
+ * @example
+ ```ts
+// config.ts
+import {enableSignalR} from '@equinor/fusion-framework-react-module-signalr';
+(configurator) => enableSignalR(configurator, 'notifications');
+
+// myHook.ts
+const myHook = () => {
+    const topic = useSignalR('notifications', 'foo');
+    return useObservableState(topic).next;
+}
+ ```
+ *
+ * @see {@link [module signalr](https://equinor.github.io/fusion-framework/modules/signalr)}
+ *
+ * @param hubId identifier of connection hub (must be configured)
+ * @param topicId identifier of topic to connect to
+ * @returns Topic
+ */
+export const useSignalR = <T>(
+  hubId: string,
+  topicId: string,
+): ReturnType<typeof useProviderTopic<T>> => {
+  const provider = useFramework<[SignalRModule]>().modules.signalR;
+  // Fail fast when the SignalRModule has not been configured on the framework
+  if (!provider) {
+    throw Error('SignalR is not configured, see @equinor/fusion-framework-react-module-signalr');
+  }
+  return useProviderTopic(provider, hubId, topicId);
+};

package/src/useFramework.ts

@@ -4,20 +4,34 @@ import type { AnyModule } from '@equinor/fusion-framework-module';
 import { useContext } from 'react';
 import { context } from './context';
 /**
+ * React hook that returns the current Fusion Framework instance from context.
+ *
+ * @remarks
+ * The hook first looks for a framework instance provided via
+ * {@link FrameworkProvider}. If none is found it falls back to the global
+ * `window.Fusion` object. A console warning / error is emitted when the
+ * framework cannot be resolved.
+ *
+ * @template TModules - Tuple of additional module types expected on the
+ *   framework instance (used for type-narrowing only).
+ * @returns The active {@link Fusion} instance.
+ *
  * @example
  * ```ts
- * const useSometing = () => {
- *  const fusion = useFramework();
- *  return fusion.something;
- * }
+ * const useMyService = () => {
+ *   const fusion = useFramework();
+ *   return fusion.modules.http.createClient('my-service');
+ * };
  * ```
  */
 export const useFramework = <TModules extends Array<AnyModule> = []>(): Fusion<TModules> => {
   let framework = useContext(context);
+  // Warn loudly when the framework context is missing so integrators notice the misuse
   if (!framework) {
     console.warn('could not locate fusion in context!');
   }
   framework ??= window.Fusion;
+  // Surface an error when neither context nor the global fallback has the framework instance
   if (!framework) {
     console.error('Could not load framework, might not be initiated?');
   }

package/src/useFrameworkModule.ts

@@ -8,13 +8,20 @@ import type {
 } from '@equinor/fusion-framework-module';
 
 /**
- * Retrieves a module from the framework instance based on its name.
+ * React hook that retrieves a module from the Fusion Framework by name.
  *
- * @template TType - The type of the module to retrieve.
- * @template TKey - The type of the module name.
- * @param name - The name of the module to retrieve.
- * @returns The requested module from the framework instance.
- * @throws Error if the requested module is not included in the framework instance.
+ * @template TType - The expected module type (used for type-narrowing).
+ * @template TKey - The module key string.
+ * @param name - The registered name of the module to retrieve.
+ * @returns The resolved module instance, or `undefined` if the module is
+ *   not registered.
+ *
+ * @example
+ * ```ts
+ * import type { HttpModule } from '@equinor/fusion-framework-module-http';
+ *
+ * const http = useFrameworkModule<HttpModule>('http');
+ * ```
  */
 export const useFrameworkModule = <
   TType extends AnyModule | unknown = unknown,
@@ -25,10 +32,11 @@ export const useFrameworkModule = <
   ? ModuleType<TType> | undefined
   : FusionModulesInstance[Extract<keyof FusionModulesInstance, TKey>] | undefined => {
   const framework = useFramework();
-  // TODO
+  // TODO(#5082): tighten generics so this indexed lookup no longer needs @ts-expect-error
   // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-ignore
+  // @ts-expect-error
   const module = framework.modules[name];
+  // Warn when the requested module key does not resolve to a registered module
   if (!module) {
     console.warn(`the requested module [${module}] is not included in the framework instance`);
   }

package/src/version.ts

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

package/dist/esm/hooks/use-current-user.js

@@ -1,6 +0,0 @@
-import { useFramework } from '../useFramework';
-export const useCurrentUser = () => {
-    const framework = useFramework();
-    return framework.modules.auth.account || undefined;
-};
-//# sourceMappingURL=use-current-user.js.map

package/dist/esm/hooks/use-current-user.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-current-user.js","sourceRoot":"","sources":["../../../src/hooks/use-current-user.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,GAA4B,EAAE;IAC1D,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,SAAS,CAAC;AACrD,CAAC,CAAC"}

package/dist/esm/hooks/use-http-client.js

@@ -1,14 +0,0 @@
-import { useMemo } from 'react';
-import { useFramework } from '../useFramework';
-export const useHttpClient = (name) => {
-    const framework = useFramework();
-    const client = useMemo(() => {
-        if (framework.modules.http.hasClient(name)) {
-            return framework.modules.http.createClient(name);
-        }
-        throw Error(`no configured client for key [${name}]`);
-    }, [framework, name]);
-    // TODO - abort on unmount?
-    return client;
-};
-//# sourceMappingURL=use-http-client.js.map

package/dist/esm/hooks/use-http-client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-http-client.js","sourceRoot":"","sources":["../../../src/hooks/use-http-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK/C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAyB,EAAc,EAAE;IACrE,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,KAAK,CAAC,iCAAiC,IAAI,GAAG,CAAC,CAAC;IACxD,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IACtB,2BAA2B;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/types/hooks/use-current-user.d.ts

@@ -1,2 +0,0 @@
-import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
-export declare const useCurrentUser: () => AccountInfo | undefined;

package/dist/types/hooks/use-http-client.d.ts

@@ -1,5 +0,0 @@
-import type { Fusion } from '@equinor/fusion-framework';
-type HttpClient = ReturnType<Fusion['modules']['http']['createClient']>;
-type FrameworkHttpClient = 'portal' | 'people';
-export declare const useHttpClient: (name: FrameworkHttpClient) => HttpClient;
-export {};

package/src/hooks/use-current-user.ts

@@ -1,7 +0,0 @@
-import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
-import { useFramework } from '../useFramework';
-
-export const useCurrentUser = (): AccountInfo | undefined => {
-  const framework = useFramework();
-  return framework.modules.auth.account || undefined;
-};

package/src/hooks/use-http-client.ts

@@ -1,19 +0,0 @@
-import { useMemo } from 'react';
-import type { Fusion } from '@equinor/fusion-framework';
-import { useFramework } from '../useFramework';
-
-type HttpClient = ReturnType<Fusion['modules']['http']['createClient']>;
-type FrameworkHttpClient = 'portal' | 'people';
-
-export const useHttpClient = (name: FrameworkHttpClient): HttpClient => {
-  const framework = useFramework();
-
-  const client = useMemo(() => {
-    if (framework.modules.http.hasClient(name)) {
-      return framework.modules.http.createClient(name);
-    }
-    throw Error(`no configured client for key [${name}]`);
-  }, [framework, name]);
-  // TODO - abort on unmount?
-  return client;
-};