feat: load spectra from external sources via spectra query param

.ncurc.yml

@@ -4,3 +4,4 @@ reject:
   - react-dom
   - '@types/react'
   - '@types/react-dom'
+  - eslint

package.json

@@ -10,22 +10,19 @@
     "src"
   ],
   "volta": {
-    "node": "24.4.0"
+    "node": "24.19.0"
   },
   "dependencies": {
-    "@blueprintjs/core": "^6.16.0",
-    "@blueprintjs/icons": "^6.11.0",
-    "@blueprintjs/select": "^6.3.0",
+    "@blueprintjs/core": "^6.18.0",
+    "@blueprintjs/icons": "^6.13.0",
     "@emotion/styled": "^11.14.1",
     "@vitejs/plugin-react": "^6.0.2",
-    "@zakodium/nmrium-core": "^0.7.30",
-    "@zakodium/nmrium-core-plugins": "^0.7.39",
+    "@zakodium/nmrium-core": "^0.7.62",
+    "@zakodium/nmrium-core-plugins": "^0.7.83",
     "fifo-logger": "^2.0.1",
-    "filelist-utils": "^1.11.3",
-    "nmr-processing": "^22.13.0",
-    "nmrium": "^2.2.0",
-    "openchemlib": "^9.23.0",
-    "react-science": "^19.11.0"
+    "nmrium": "^2.6.0",
+    "openchemlib": "^9.25.0",
+    "react-science": "^23.0.1"
   },
   "scripts": {
     "start": "vite --host localhost --port 3000  --open",
@@ -46,25 +43,24 @@
     "@babel/plugin-transform-modules-commonjs": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
-    "@playwright/test": "^1.61.0",
+    "@playwright/test": "^1.62.1",
     "@simbathesailor/use-what-changed": "^2.0.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.2.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
-    "@types/react-router-dom": "^5.3.3",
     "cross-env": "^10.1.0",
     "eslint": "^9.39.2",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
     "jest": "^30.4.2",
-    "prettier": "3.8.4",
+    "prettier": "3.9.6",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-router-dom": "^7.17.0",
+    "react-router-dom": "^7.18.2",
     "serve": "^14.2.6",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16",
+    "vite": "^8.2.2",
     "vite-plugin-pwa": "^1.3.0"
   }
 }

src/NMRiumWrapper.tsx

@@ -5,6 +5,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { RootLayout } from 'react-science/ui';
 
 import { LoadingIndicator } from './Loadingindicator.js';
+import { loadSpectraFromSource } from './data-source/loadSpectraFromSource.js';
 import events from './events/event.js';
 import { useLoadSpectra } from './hooks/useLoadSpectra.js';
 import { usePreferences } from './hooks/usePreferences.js';
@@ -20,8 +21,13 @@ const containerStyle: CSSProperties = {
 export default function NMRiumWrapper() {
   const { allowedOrigins, isFetchAllowedOriginsPending } = useWhiteList();
   const nmriumRef = useRef<NMRiumRefAPI>(null);
-  const { workspace, preferences, defaultEmptyMessage, customWorkspaces } =
-    usePreferences();
+  const {
+    workspace,
+    preferences,
+    defaultEmptyMessage,
+    customWorkspaces,
+    spectraSource,
+  } = usePreferences();
 
   const { load: loadSpectra, data, isLoading, setActiveTab } = useLoadSpectra();
 
@@ -33,6 +39,25 @@ export default function NMRiumWrapper() {
     events.trigger('data-change', { state, source });
   }, []);
 
+  useEffect(() => {
+    if (!spectraSource) return;
+
+    const { source, id } = spectraSource;
+
+    async function loadFromSource() {
+      try {
+        const nmrium = await loadSpectraFromSource(source, id);
+        void loadSpectra({ nmrium });
+      } catch (error) {
+        events.trigger('error', error as Error);
+        // eslint-disable-next-line no-console
+        console.error(error);
+      }
+    }
+
+    void loadFromSource();
+  }, [spectraSource, loadSpectra]);
+
   useEffect(() => {
     const clearActionListener = events.on(
       'action-request',
@@ -73,13 +98,13 @@ export default function NMRiumWrapper() {
             break;
           }
           case 'file': {
-            const { data: files, activeTab = '' } = loadData;
-            void loadSpectra({ files, activeTab });
+            const { data: files, activeTab = '', fileFilter } = loadData;
+            void loadSpectra({ files, activeTab, fileFilter });
             break;
           }
           case 'url': {
-            const { data: urls, activeTab = '' } = loadData;
-            void loadSpectra({ urls, activeTab });
+            const { data: urls, activeTab = '', fileFilter } = loadData;
+            void loadSpectra({ urls, activeTab, fileFilter });
             break;
           }
           default: {

src/config/nmrxiv/index.ts

@@ -0,0 +1,10 @@
+import development from './nmrxiv.development.json' with { type: 'json' };
+import production from './nmrxiv.production.json' with { type: 'json' };
+
+interface NmrXivConfig {
+  baseURL: string;
+}
+
+export const nmrXivConfig: NmrXivConfig = import.meta.env.DEV
+  ? development
+  : production;

src/config/nmrxiv/nmrxiv.development.json

@@ -0,0 +1,3 @@
+{
+    "baseURL": "https://dev.nmrxiv.org/api/v1/samples"
+}

src/config/nmrxiv/nmrxiv.production.json

@@ -0,0 +1,3 @@
+{
+    "baseURL": "https://nmrxiv.org/api/v1/samples"
+}

src/data-source/loadSpectraFromSource.ts

@@ -0,0 +1,20 @@
+import { loadNmrXivSpectraById } from './nmrxiv.js';
+
+export type SpectraSource = 'nmrxiv';
+
+type SpectraSourceLoader = (id: string) => Promise<object>;
+
+const spectraSourceLoaders: Record<SpectraSource, SpectraSourceLoader> = {
+  nmrxiv: loadNmrXivSpectraById,
+};
+
+export async function loadSpectraFromSource(
+  source: string,
+  id: string,
+): Promise<object> {
+  const loader = spectraSourceLoaders[source];
+  if (!loader) {
+    throw new Error(`Unknown spectra source: "${source}"`);
+  }
+  return loader(id);
+}

src/data-source/nmrxiv.ts

@@ -0,0 +1,17 @@
+import { nmrXivConfig } from '../config/nmrxiv/index.js';
+
+function getNmrXivSpectraJsonURL(id: string): string {
+  return `${nmrXivConfig.baseURL}/${id}/nmriumInfo`;
+}
+
+export async function loadNmrXivSpectraById(id: string): Promise<object> {
+  const response = await fetch(getNmrXivSpectraJsonURL(id));
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch nmrXiv spectra "${id}" (status ${response.status})`,
+    );
+  }
+
+  return response.json();
+}

src/events/types.ts

@@ -1,3 +1,4 @@
+import type { FilterOptions } from 'file-collection';
 import type { NMRiumData, NMRiumState } from 'nmrium';
 
 interface BlobObject {
@@ -6,21 +7,19 @@ interface BlobObject {
   height: number;
 }
 type EventType =
-  | 'load'
-  | 'data-change'
-  | 'error'
-  | 'action-request'
-  | 'action-response';
+  'load' | 'data-change' | 'error' | 'action-request' | 'action-response';
 
 type LoadData =
   | {
       data: string[];
       activeTab?: string;
+      fileFilter?: FilterOptions;
       type: 'url';
     }
   | {
       data: File[];
       activeTab?: string;
+      fileFilter?: FilterOptions;
       type: 'file';
     }
   | {

src/hooks/useLoadSpectra.ts

@@ -7,17 +7,35 @@ import type {
 import { CURRENT_EXPORT_VERSION } from '@zakodium/nmrium-core';
 import init from '@zakodium/nmrium-core-plugins';
 import { FifoLogger } from 'fifo-logger';
+import type { FilterOptions } from 'file-collection';
 import { FileCollection } from 'file-collection';
 import { useCallback, useMemo, useState } from 'react';
 
 import events from '../events/event.js';
 import { getFileNameFromURL } from '../utilities/getFileNameFromURL.js';
 import { isArrayOfString } from '../utilities/isArrayOfString.js';
 
-type LoadOptions =
-  | { nmrium: object; activeTab?: string }
-  | { urls: string[]; activeTab?: string }
-  | { files: File[]; activeTab?: string };
+interface BaseLoadOptions {
+  activeTab?: string;
+}
+
+interface FileLoadOptions extends BaseLoadOptions {
+  fileFilter?: FilterOptions;
+}
+
+interface NMRiumLoadOptions extends BaseLoadOptions {
+  nmrium: object;
+}
+
+interface URLsLoadOptions extends FileLoadOptions {
+  urls: string[];
+}
+
+interface FilesLoadOptions extends FileLoadOptions {
+  files: File[];
+}
+
+type LoadOptions = NMRiumLoadOptions | URLsLoadOptions | FilesLoadOptions;
 
 // CoreReadReturn with `state.view` made optional to allow partial injection.
 export type NMRiumData = Omit<CoreReadReturn, 'state'> & {
@@ -51,16 +69,27 @@ const PARSING_OPTIONS: Partial<ParsingOptions> = {
   logger,
 };
 
-async function loadSpectraFromNMRium(nmrium: object): Promise<CoreReadReturn> {
+async function loadSpectraFromNMRium({
+  nmrium,
+}: NMRiumLoadOptions): Promise<CoreReadReturn> {
   return core.readNMRiumObject(nmrium, PARSING_OPTIONS);
 }
 
-async function loadSpectraFromFiles(files: File[]): Promise<CoreReadReturn> {
-  const fileCollection = await new FileCollection().appendFileList(files);
+async function loadSpectraFromFiles(
+  options: FilesLoadOptions,
+): Promise<CoreReadReturn> {
+  const { files, fileFilter } = options;
+  const fileCollection = await new FileCollection({
+    filter: fileFilter,
+  }).appendFileList(files);
+
   return core.read(fileCollection, PARSING_OPTIONS);
 }
 
-async function loadSpectraFromURLs(urls: string[]): Promise<CoreReadReturn> {
+async function loadSpectraFromURLs(
+  options: URLsLoadOptions,
+): Promise<CoreReadReturn> {
+  const { urls, fileFilter } = options;
   const entries = urls.map((url) => {
     const refURL = new URL(url);
     const name = getFileNameFromURL(url);
@@ -73,7 +102,10 @@ async function loadSpectraFromURLs(urls: string[]): Promise<CoreReadReturn> {
     return { relativePath: path, baseURL: refURL.origin };
   });
 
-  return core.readFromWebSource({ entries }, PARSING_OPTIONS);
+  return core.readFromWebSource(
+    { entries },
+    { ...PARSING_OPTIONS, fileFilter },
+  );
 }
 
 export function useLoadSpectra(): UseLoadSpectraResult {
@@ -88,17 +120,17 @@ export function useLoadSpectra(): UseLoadSpectraResult {
       let resolvedActiveTab: string | undefined;
 
       if ('nmrium' in options) {
-        loadedResult = await loadSpectraFromNMRium(options.nmrium);
+        loadedResult = await loadSpectraFromNMRium(options);
         resolvedActiveTab =
           options.activeTab ?? loadedResult.state.view?.spectra?.activeTab;
       } else if ('urls' in options) {
         if (!isArrayOfString(options.urls)) {
           throw new Error('The input must be a valid urls array of string[]');
         }
-        loadedResult = await loadSpectraFromURLs(options.urls);
+        loadedResult = await loadSpectraFromURLs(options);
         resolvedActiveTab = options.activeTab;
       } else {
-        loadedResult = await loadSpectraFromFiles(options.files);
+        loadedResult = await loadSpectraFromFiles(options);
         resolvedActiveTab = options.activeTab;
       }
 

src/hooks/usePreferences.ts

@@ -3,7 +3,9 @@ import type {
   WorkspacePreferences,
 } from '@zakodium/nmrium-core';
 import type { NMRiumWorkspace } from 'nmrium';
+import { useMemo } from 'react';
 
+import { parseSpectraSource } from '../utilities/parseSpectraSource.js';
 import type { WorkspaceOptions } from '../workspaces/integration.js';
 import { getIntegrationWorkspace } from '../workspaces/integration.js';
 import { getNmrXivWorkspace } from '../workspaces/nmrxiv.js';
@@ -58,11 +60,18 @@ export function usePreferences() {
       parameters.get('hidePanelOnLoad')?.toLowerCase() === 'true';
   }
 
+  const rawSpectra = parameters.get('spectra');
+  const spectraSource = useMemo(
+    () => parseSpectraSource(rawSpectra),
+    [rawSpectra],
+  );
+
   return {
     preferences,
     workspace,
     defaultEmptyMessage,
     customWorkspaces,
+    spectraSource,
   };
 }
 

src/utilities/parseSpectraSource.ts

@@ -0,0 +1,25 @@
+export interface SpectraSource {
+  source: string;
+  id: string;
+}
+
+/**
+ * Parses a `spectra` query parameter in the format `<source>:<id>` and returns an object with `source` and `id` properties.
+ *
+ * Example:
+ * `nmrxiv:S2173` => { source: 'nmrxiv', id: 'S2173' }
+ */
+export function parseSpectraSource(
+  value: string | null,
+): SpectraSource | undefined {
+  if (!value) return undefined;
+
+  const separatorIndex = value.indexOf(':');
+  if (separatorIndex === -1) return undefined;
+
+  const source = value.slice(0, separatorIndex).trim();
+  const id = value.slice(separatorIndex + 1).trim();
+  if (!source || !id) return undefined;
+
+  return { source, id };
+}