@imfusion/sdk-react 0.7.0-dev.31.g0ba92924

package/README.md

@@ -0,0 +1,51 @@
+# ImFusion Web SDK React Bindings
+React components and hooks for integrating the ImFusion Web SDK into React applications.
+
+## Getting Started
+
+Wrap your app with `ImFusionProvider`, add a canvas, and use the lifecycle components:
+
+```tsx
+import {
+  ImFusionProvider,
+  ImFusionCanvas,
+  ImFusionReady,
+  ImFusionLoading,
+  ImFusionError,
+} from '@imfusion/sdk-react';
+
+function App() {
+  return (
+    <ImFusionProvider>
+      <ImFusionCanvas style={{ width: '100%', height: '100%' }} />
+      <ImFusionLoading>Initializing SDK...</ImFusionLoading>
+      <ImFusionError>{error => <p>Failed: {error.message}</p>}</ImFusionError>
+      <ImFusionReady>
+        <Viewer />
+      </ImFusionReady>
+    </ImFusionProvider>
+  );
+}
+```
+
+Inside `ImFusionReady`, use hooks to interact with the SDK:
+
+```tsx
+import { useImFusion, useDataLoader, useData } from '@imfusion/sdk-react';
+
+function Viewer() {
+  const imf = useImFusion();
+  const { loadUrl, isLoading, progress } = useDataLoader();
+  const datasets = useData();
+
+  return (
+    <div>
+      <button onClick={() => loadUrl('/data/scan.nii.gz')} disabled={isLoading}>
+        {isLoading ? 'Loading...' : 'Load'}
+      </button>
+      <p>{datasets.length} dataset(s) loaded</p>
+    </div>
+  );
+}
+```
+

package/dist/ImFusionCanvas.d.ts

@@ -0,0 +1,26 @@
+import { type CanvasHTMLAttributes } from 'react';
+/**
+ * Renders a canvas element and registers it with the {@link ImFusionProvider}.
+ *
+ * When this component mounts, it triggers SDK initialization by registering
+ * the canvas element with the parent provider. All standard HTML canvas
+ * attributes are passed through to the underlying `<canvas>` element.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas
+ *     style={{ width: '100%', height: '100vh' }}
+ *     className="viewer-canvas"
+ *   />
+ * </ImFusionProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Accessing the canvas element via ref
+ * const canvasRef = useRef<HTMLCanvasElement>(null);
+ * <ImFusionCanvas ref={canvasRef} width={800} height={600} />
+ * ```
+ */
+export declare const ImFusionCanvas: import("react").ForwardRefExoticComponent<CanvasHTMLAttributes<HTMLCanvasElement> & import("react").RefAttributes<HTMLCanvasElement>>;

package/dist/ImFusionCanvas.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useEffect, useRef, forwardRef } from 'react';
+import { ImFusionContext } from './context.js';
+/**
+ * Renders a canvas element and registers it with the {@link ImFusionProvider}.
+ *
+ * When this component mounts, it triggers SDK initialization by registering
+ * the canvas element with the parent provider. All standard HTML canvas
+ * attributes are passed through to the underlying `<canvas>` element.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas
+ *     style={{ width: '100%', height: '100vh' }}
+ *     className="viewer-canvas"
+ *   />
+ * </ImFusionProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Accessing the canvas element via ref
+ * const canvasRef = useRef<HTMLCanvasElement>(null);
+ * <ImFusionCanvas ref={canvasRef} width={800} height={600} />
+ * ```
+ */
+export const ImFusionCanvas = forwardRef(function ImFusionCanvas(props, forwardedRef) {
+    const context = useContext(ImFusionContext);
+    const internalRef = useRef(null);
+    if (!context) {
+        throw new Error('ImFusionCanvas must be used within an ImFusionProvider');
+    }
+    useEffect(() => {
+        const canvas = internalRef.current;
+        if (canvas) {
+            context.registerCanvas(canvas);
+        }
+    }, [context.registerCanvas]);
+    // Merge the internal ref with the forwarded ref
+    const setRefs = (element) => {
+        internalRef.current = element;
+        if (typeof forwardedRef === 'function') {
+            forwardedRef(element);
+        }
+        else if (forwardedRef) {
+            forwardedRef.current = element;
+        }
+    };
+    return _jsx("canvas", { ref: setRefs, ...props });
+});

package/dist/ImFusionError.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from 'react';
+export interface ImFusionErrorProps {
+    /** Content to render when an initialization error has occurred. */
+    children: ReactNode;
+}
+/**
+ * Renders children when SDK initialization has failed.
+ *
+ * Use {@link useImFusionError} inside children to access the error object.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionLoading>
+ *     <Spinner />
+ *   </ImFusionLoading>
+ *   <ImFusionError>
+ *     <ErrorDisplay />
+ *   </ImFusionError>
+ *   <ImFusionReady>
+ *     <App />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * ```tsx
+ * function ErrorDisplay() {
+ *   const error = useImFusionError();
+ *   return <p>Failed to initialize: {error.message}</p>;
+ * }
+ * ```
+ *
+ * @see {@link useImFusionError}
+ * @see {@link useImFusionState}
+ */
+export declare function ImFusionError({ children }: ImFusionErrorProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/ImFusionError.js

@@ -0,0 +1,41 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { ImFusionContext } from './context.js';
+/**
+ * Renders children when SDK initialization has failed.
+ *
+ * Use {@link useImFusionError} inside children to access the error object.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionLoading>
+ *     <Spinner />
+ *   </ImFusionLoading>
+ *   <ImFusionError>
+ *     <ErrorDisplay />
+ *   </ImFusionError>
+ *   <ImFusionReady>
+ *     <App />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * ```tsx
+ * function ErrorDisplay() {
+ *   const error = useImFusionError();
+ *   return <p>Failed to initialize: {error.message}</p>;
+ * }
+ * ```
+ *
+ * @see {@link useImFusionError}
+ * @see {@link useImFusionState}
+ */
+export function ImFusionError({ children }) {
+    const context = useContext(ImFusionContext);
+    if (!context) {
+        throw new Error('ImFusionError must be used within an ImFusionProvider');
+    }
+    return context.error ? _jsx(_Fragment, { children: children }) : null;
+}

package/dist/ImFusionLoading.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+export interface ImFusionLoadingProps {
+    children: ReactNode;
+}
+/**
+ * Renders children while the SDK is initializing.
+ *
+ * Automatically hides when the SDK becomes ready or when an error occurs.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionLoading>
+ *     <div className="spinner">Loading SDK...</div>
+ *   </ImFusionLoading>
+ *   <ImFusionReady>
+ *     <App />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @see {@link useImFusionState}
+ */
+export declare function ImFusionLoading({ children }: ImFusionLoadingProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/ImFusionLoading.js

@@ -0,0 +1,30 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { ImFusionContext } from './context.js';
+/**
+ * Renders children while the SDK is initializing.
+ *
+ * Automatically hides when the SDK becomes ready or when an error occurs.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionLoading>
+ *     <div className="spinner">Loading SDK...</div>
+ *   </ImFusionLoading>
+ *   <ImFusionReady>
+ *     <App />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @see {@link useImFusionState}
+ */
+export function ImFusionLoading({ children }) {
+    const context = useContext(ImFusionContext);
+    if (!context) {
+        throw new Error('ImFusionLoading must be used within an ImFusionProvider');
+    }
+    return !context.imf && !context.error ? _jsx(_Fragment, { children: children }) : null;
+}

package/dist/ImFusionProvider.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from 'react';
+import { type ImFusion, type InitOptions } from '@imfusion/sdk';
+export interface ImFusionProviderProps {
+    /**
+     * Options passed to {@link @imfusion/sdk!init | init} when the SDK is initialized.
+     *
+     * @see {@link @imfusion/sdk!InitOptions | InitOptions}
+     */
+    options?: InitOptions;
+    /**
+     * Called after the SDK has been initialized successfully.
+     */
+    onReady?: (imf: ImFusion) => void;
+    /**
+     * Called if SDK initialization fails.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Content that should have access to the ImFusion SDK.
+     *
+     * Render an {@link ImFusionCanvas} somewhere inside this provider so the SDK
+     * has a canvas to initialize against.
+     */
+    children: ReactNode;
+}
+/**
+ * Initializes the ImFusion SDK and provides it to descendant components.
+ *
+ * Place an {@link ImFusionCanvas} inside this provider to trigger initialization.
+ * Children are rendered immediately; use the state components to show different
+ * UI for each initialization phase.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider options={{ autoResize: true }}>
+ *   <ImFusionCanvas style={{ width: '100%', height: '100vh' }} />
+ *
+ *   <ImFusionLoading>
+ *     <Spinner />
+ *   </ImFusionLoading>
+ *
+ *   <ImFusionError>
+ *     <ErrorMessage />
+ *   </ImFusionError>
+ *
+ *   <ImFusionReady>
+ *     <MyApp />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @remarks
+ * The SDK is initialized once per provider instance. Changes to `options` do
+ * not reconfigure an already initialized SDK.
+ */
+export declare function ImFusionProvider({ options, onReady, onError, children }: ImFusionProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/ImFusionProvider.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { init } from '@imfusion/sdk';
+import { ImFusionContext } from './context.js';
+/**
+ * Initializes the ImFusion SDK and provides it to descendant components.
+ *
+ * Place an {@link ImFusionCanvas} inside this provider to trigger initialization.
+ * Children are rendered immediately; use the state components to show different
+ * UI for each initialization phase.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider options={{ autoResize: true }}>
+ *   <ImFusionCanvas style={{ width: '100%', height: '100vh' }} />
+ *
+ *   <ImFusionLoading>
+ *     <Spinner />
+ *   </ImFusionLoading>
+ *
+ *   <ImFusionError>
+ *     <ErrorMessage />
+ *   </ImFusionError>
+ *
+ *   <ImFusionReady>
+ *     <MyApp />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @remarks
+ * The SDK is initialized once per provider instance. Changes to `options` do
+ * not reconfigure an already initialized SDK.
+ */
+export function ImFusionProvider({ options, onReady, onError, children }) {
+    const [canvas, setCanvas] = useState(null);
+    const [imf, setImf] = useState(null);
+    const [error, setError] = useState(null);
+    // Capture init promise to prevent double WASM creation in StrictMode
+    const initPromiseRef = useRef(null);
+    // Capture the first canvas; warn if a different one tries to register
+    const initialCanvasRef = useRef(null);
+    // Capture initial options only (never updated)
+    const optionsRef = useRef(options);
+    const onReadyRef = useRef(onReady);
+    const onErrorRef = useRef(onError);
+    onReadyRef.current = onReady;
+    onErrorRef.current = onError;
+    const registerCanvas = useCallback((canvasElement) => {
+        if (initialCanvasRef.current) {
+            if (initialCanvasRef.current !== canvasElement) {
+                console.warn('ImFusionProvider: A different canvas element was registered after SDK initialization. ' +
+                    'The SDK remains bound to the original canvas.');
+            }
+            return;
+        }
+        initialCanvasRef.current = canvasElement;
+        setCanvas(canvasElement);
+    }, []);
+    useEffect(() => {
+        if (!canvas)
+            return;
+        let cancelled = false;
+        if (!initPromiseRef.current) {
+            initPromiseRef.current = init(canvas, optionsRef.current);
+        }
+        initPromiseRef.current
+            .then((instance) => {
+            if (!cancelled) {
+                setImf(instance);
+                onReadyRef.current?.(instance);
+            }
+        })
+            .catch((err) => {
+            if (!cancelled) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                onErrorRef.current?.(error);
+            }
+        });
+        return () => {
+            cancelled = true;
+            initPromiseRef.current?.then((instance) => instance.destroy());
+        };
+    }, [canvas]);
+    const contextValue = useMemo(() => ({ imf, error, registerCanvas }), [imf, error, registerCanvas]);
+    return _jsx(ImFusionContext.Provider, { value: contextValue, children: children });
+}

package/dist/ImFusionReady.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+export interface ImFusionReadyProps {
+    children: ReactNode;
+}
+/**
+ * Renders children only after the SDK has successfully initialized.
+ *
+ * Components inside can safely call {@link useImFusion}. Multiple instances
+ * can be placed independently throughout the tree.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionReady>
+ *     <Sidebar />
+ *     <Toolbar />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @see {@link useImFusion}
+ * @see {@link useImFusionState}
+ */
+export declare function ImFusionReady({ children }: ImFusionReadyProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/ImFusionReady.js

@@ -0,0 +1,30 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { ImFusionContext } from './context.js';
+/**
+ * Renders children only after the SDK has successfully initialized.
+ *
+ * Components inside can safely call {@link useImFusion}. Multiple instances
+ * can be placed independently throughout the tree.
+ *
+ * @example
+ * ```tsx
+ * <ImFusionProvider>
+ *   <ImFusionCanvas />
+ *   <ImFusionReady>
+ *     <Sidebar />
+ *     <Toolbar />
+ *   </ImFusionReady>
+ * </ImFusionProvider>
+ * ```
+ *
+ * @see {@link useImFusion}
+ * @see {@link useImFusionState}
+ */
+export function ImFusionReady({ children }) {
+    const context = useContext(ImFusionContext);
+    if (!context) {
+        throw new Error('ImFusionReady must be used within an ImFusionProvider');
+    }
+    return context.imf ? _jsx(_Fragment, { children: children }) : null;
+}

package/dist/context.d.ts

@@ -0,0 +1,14 @@
+import type { ImFusion } from '@imfusion/sdk';
+/**
+ * Internal context value shared between provider, canvas, and hooks.
+ *
+ * @internal Use {@link useImFusion},
+ * {@link useImFusionError}, or {@link useImFusionState} instead.
+ */
+export interface ImFusionContextValue {
+    imf: ImFusion | null;
+    error: Error | null;
+    registerCanvas: (canvas: HTMLCanvasElement) => void;
+}
+/** @internal */
+export declare const ImFusionContext: import("react").Context<ImFusionContextValue | null>;

package/dist/context.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+/** @internal */
+export const ImFusionContext = createContext(null);

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { ImFusionProvider, type ImFusionProviderProps } from './ImFusionProvider.js';
+export { ImFusionCanvas } from './ImFusionCanvas.js';
+export { ImFusionReady, type ImFusionReadyProps } from './ImFusionReady.js';
+export { ImFusionLoading, type ImFusionLoadingProps } from './ImFusionLoading.js';
+export { ImFusionError, type ImFusionErrorProps } from './ImFusionError.js';
+export { useImFusion } from './useImFusion.js';
+export { useImFusionError } from './useImFusionError.js';
+export { useImFusionState, type ImFusionState } from './useImFusionState.js';
+export { useData } from './useData.js';
+export { useVisibleData } from './useVisibleData.js';
+export { useDataLoader, type DataLoaderProgress } from './useDataLoader.js';
+export { useAnnotations } from './useAnnotations.js';
+export { useLayoutMode } from './useLayoutMode.js';
+export { useViewVisibility } from './useViewVisibility.js';
+export { useDisplayOptions2d, useDisplayOptions3d } from './useDisplayOptions.js';
+export { useFrameSelection } from './useFrameSelection.js';
+export { useContextMenu } from './useContextMenu.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { ImFusionProvider } from './ImFusionProvider.js';
+export { ImFusionCanvas } from './ImFusionCanvas.js';
+export { ImFusionReady } from './ImFusionReady.js';
+export { ImFusionLoading } from './ImFusionLoading.js';
+export { ImFusionError } from './ImFusionError.js';
+export { useImFusion } from './useImFusion.js';
+export { useImFusionError } from './useImFusionError.js';
+export { useImFusionState } from './useImFusionState.js';
+export { useData } from './useData.js';
+export { useVisibleData } from './useVisibleData.js';
+export { useDataLoader } from './useDataLoader.js';
+export { useAnnotations } from './useAnnotations.js';
+export { useLayoutMode } from './useLayoutMode.js';
+export { useViewVisibility } from './useViewVisibility.js';
+export { useDisplayOptions2d, useDisplayOptions3d } from './useDisplayOptions.js';
+export { useFrameSelection } from './useFrameSelection.js';
+export { useContextMenu } from './useContextMenu.js';

package/dist/useAnnotations.d.ts

@@ -0,0 +1,33 @@
+import type { Annotation, Data, HandleArray } from '@imfusion/sdk';
+/**
+ * Returns a reactive list of annotations, optionally filtered by dataset.
+ *
+ * Subscribes to {@link @imfusion/sdk!AnnotationModel.onAnnotationAdded | AnnotationModel.onAnnotationAdded},
+ * {@link @imfusion/sdk!AnnotationModel.onAnnotationAboutToBeRemoved | AnnotationModel.onAnnotationAboutToBeRemoved}, and
+ * {@link @imfusion/sdk!AnnotationModel.onAnnotationEvent | AnnotationModel.onAnnotationEvent}.
+ *
+ * When `data` is provided, only annotations belonging to that dataset are
+ * returned.
+ *
+ * @param data - Optional dataset to filter annotations by
+ * @returns A {@link @imfusion/sdk!HandleArray | HandleArray} of annotations
+ * @throws If called outside of an {@link ImFusionProvider}
+ * @throws If called before the SDK has finished initializing
+ *
+ * @example
+ * ```tsx
+ * function AnnotationList() {
+ *   const annotations = useAnnotations();
+ *   return <p>Total annotations: {annotations.length}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function DataAnnotations({ data }: { data: Data }) {
+ *   const annotations = useAnnotations(data);
+ *   return <p>Annotations on {data.name}: {annotations.length}</p>;
+ * }
+ * ```
+ */
+export declare function useAnnotations(data?: Data): HandleArray<Annotation>;

package/dist/useAnnotations.js

@@ -0,0 +1,67 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useImFusion } from './useImFusion.js';
+import { useStableHandle } from './useStableHandle.js';
+/**
+ * Returns a reactive list of annotations, optionally filtered by dataset.
+ *
+ * Subscribes to {@link @imfusion/sdk!AnnotationModel.onAnnotationAdded | AnnotationModel.onAnnotationAdded},
+ * {@link @imfusion/sdk!AnnotationModel.onAnnotationAboutToBeRemoved | AnnotationModel.onAnnotationAboutToBeRemoved}, and
+ * {@link @imfusion/sdk!AnnotationModel.onAnnotationEvent | AnnotationModel.onAnnotationEvent}.
+ *
+ * When `data` is provided, only annotations belonging to that dataset are
+ * returned.
+ *
+ * @param data - Optional dataset to filter annotations by
+ * @returns A {@link @imfusion/sdk!HandleArray | HandleArray} of annotations
+ * @throws If called outside of an {@link ImFusionProvider}
+ * @throws If called before the SDK has finished initializing
+ *
+ * @example
+ * ```tsx
+ * function AnnotationList() {
+ *   const annotations = useAnnotations();
+ *   return <p>Total annotations: {annotations.length}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function DataAnnotations({ data }: { data: Data }) {
+ *   const annotations = useAnnotations(data);
+ *   return <p>Annotations on {data.name}: {annotations.length}</p>;
+ * }
+ * ```
+ */
+export function useAnnotations(data) {
+    const imf = useImFusion();
+    const stableData = useStableHandle(data);
+    const readAnnotations = useCallback(() => {
+        return stableData ? imf.annotationModel.dataAnnotations(stableData) : imf.annotationModel.annotations();
+    }, [imf, stableData]);
+    const [annotations, setAnnotations] = useState(readAnnotations);
+    useEffect(() => {
+        setAnnotations(readAnnotations());
+        const refresh = () => {
+            setAnnotations((prev) => {
+                const next = readAnnotations();
+                if (prev.length !== next.length)
+                    return next;
+                for (let i = 0; i < prev.length; i++) {
+                    if (!prev[i].isAliasOf(next[i]))
+                        return next;
+                }
+                return prev;
+            });
+        };
+        const deferredRefresh = () => queueMicrotask(refresh);
+        const offAdded = imf.annotationModel.onAnnotationAdded(refresh);
+        const offRemoved = imf.annotationModel.onAnnotationAboutToBeRemoved(deferredRefresh);
+        const offEvent = imf.annotationModel.onAnnotationEvent(refresh);
+        return () => {
+            offAdded();
+            offRemoved();
+            offEvent();
+        };
+    }, [imf, readAnnotations]);
+    return annotations;
+}

package/dist/useContextMenu.d.ts

@@ -0,0 +1,21 @@
+import type { Menu } from '@imfusion/sdk';
+/**
+ * Registers a context menu handler that fires when the SDK produces a
+ * context menu from an input event.
+ *
+ * @param callback - Receives the {@link @imfusion/sdk!Menu | Menu} and the DOM {@link Event} that triggered it
+ * @throws If called outside of an {@link ImFusionProvider}
+ * @throws If called before the SDK has finished initializing
+ *
+ * @example
+ * ```tsx
+ * function ContextMenuHandler() {
+ *   useContextMenu((menu, event) => {
+ *     event.preventDefault();
+ *     // Build a custom menu UI from menu.items()
+ *   });
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useContextMenu(callback: (menu: Menu, event: Event) => void): void;