@e-infra/react-molstar-wrapper 0.0.8

package/dist/types/react/Viewer.d.ts

@@ -0,0 +1,86 @@
+import { Props, ViewerRef } from './types';
+/**
+ * Viewer
+ *
+ * React component that embeds a Mol* viewer plugin and exposes a small imperative
+ * API via a forwarded ref. The component is responsible for initializing and
+ * releasing a shared plugin instance (via Manager), loading structure data (either
+ * from raw `proteins` input or from precomputed `mvs`), and exposing convenience
+ * controls such as background color and simple animations (spin/rock).
+ *
+ * Remarks
+ * - Exactly one of `proteins` or `mvs` must be provided. Passing both or neither
+ *   will throw an error during initialization.
+ * - The component holds internal loading state: "loading" | "success" | "error".
+ *   On initialization errors the state becomes "error" and the error is logged to
+ *   the console.
+ * - The plugin instance is created/reused via Manager.getInstance() and is
+ *   released when the component unmounts (or when the effect cleans up).
+ * - UI mode `initialUI` toggles whether control chrome is shown; when set to
+ *   "minimal" an additional CSS class ("no-controls") is applied to the container.
+ *
+ * Props
+ * @param proteins - Optional raw proteins data used to construct an MVS representation.
+ *   When provided, the component will call `createMVS(proteins, modelSourceUrls, plugin)`
+ *   to compute the view state to load into the plugin.
+ * @param mvs - Optional precomputed MVS data. If provided, the viewer loads this
+ *   directly and does not call `createMVS`.
+ * @param modelSourceUrls - Optional lookup mapping used by `createMVS` to resolve
+ *   model source URLs for remote model retrieval when `proteins` is used.
+ *   Without trailing slashes, e.g. { uniProtId: "https://api.example.com/protein" }.
+ * @param initialUI - Which initial UI preset to use for the embedded plugin.
+ *   Typical values: "standard" | "minimal". Default: "standard".
+ * @param bgColor - Background color for the viewer (any valid CSS color). Default: "#ffffff".
+ * @param spin - Whether to enable continuous spin animation. Mutually exclusive with `rock`.
+ * @param spinSpeed - Speed multiplier for the spin animation. Default: 0.05.
+ * @param rock - Whether to enable rock animation (back-and-forth). Mutually exclusive with `spin`.
+ * @param rockSpeed - Speed multiplier for the rock animation. Default: 0.2.
+ * @param height - Optional explicit height (in pixels) for the outer wrapper. If omitted,
+ *   the wrapper will fill available height ("100%").
+ * @param className - Optional CSS class to apply to the outer wrapper.
+ *
+ * Forwarded ref (ViewerRef)
+ * The component forwards a ref exposing the following async methods:
+ * - highlight(domainId: number): Promise<void>
+ *     Focuses/highlights a domain in the first protein using its choppingData.
+ *     No-op if plugin or choppingData is not available.
+ * - reset(): Promise<void>
+ *     Resets the plugin's view to its default/original pose.
+ * - updateSuperposition(proteinIndex: number, translation?, rotation?): Promise<void>
+ *     Updates the transform for a loaded structure (protein) without reloading the
+ *     entire scene. `translation` is an optional [x, y, z] tuple. `rotation` is an
+ *     optional 3x3 matrix represented as [[r11,r12,r13],[r21,r22,r23],[r31,r32,r33]].
+ *     This method relies on the Mol* plugin API to update transforms in-place.
+ *
+ * Behavior & Side Effects
+ * - While the component is initializing the plugin and loading data, it renders a
+ *   LoaderView. If initialization fails, it renders an ErrorView.
+ * - When `spin` or `rock` props change (and the component is in "success" state),
+ *   the corresponding plugin animation is enabled with the provided speed. Passing
+ *   neither results in animations being turned off.
+ * - When `bgColor` changes (and the component is in "success" state), the plugin's
+ *   background color is updated.
+ * - The container element receives a stable id (useId) and CSS class "react-molstar",
+ *   plus "no-controls" when `initialUI === "minimal"`. The visualization container's
+ *   opacity animates between loading/success states.
+ *
+ * Example
+ * const ref = useRef<ViewerRef | null>(null);
+ * <Viewer
+ *   ref={ref}
+ *   proteins={myProteins}
+ *   initialUI="standard"
+ *   bgColor="#000"
+ * />
+ * // later
+ * await ref.current?.highlight(3);
+ * await ref.current?.updateSuperposition(1, [10,0,0], [[1,0,0],[0,1,0],[0,0,1]]);
+ *
+ * See also
+ * - Manager: plugin lifecycle management used to acquire/release plugin instances.
+ * - createMVS: helper to convert raw protein input into an MVS representation accepted
+ *   by the plugin.
+ */
+declare const Viewer: import('react').ForwardRefExoticComponent<Props & import('react').RefAttributes<ViewerRef>>;
+export default Viewer;
+//# sourceMappingURL=Viewer.d.ts.map

package/dist/types/react/Viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Viewer.d.ts","sourceRoot":"","sources":["../../../lib/react/Viewer.tsx"],"names":[],"mappings":"AAWA,OAAO,aAAa,CAAC;AACrB,OAAO,2CAA2C,CAAC;AAMnD,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,QAAA,MAAM,MAAM,6FA6MV,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/types/react/types.d.ts

@@ -0,0 +1,49 @@
+import { ColorHEX, InitialUI, ModelSourceUrls, Protein } from '../core/types';
+import { MVSData } from 'molstar/lib/extensions/mvs/mvs-data.d.ts';
+export type Props = {} & ({
+    proteins: Protein[];
+    mvs?: never;
+} | {
+    mvs: MVSData;
+    proteins?: never;
+}) & {
+    modelSourceUrls?: Partial<ModelSourceUrls>;
+    initialUI?: InitialUI;
+    bgColor?: ColorHEX;
+} & ({
+    spin: boolean;
+    rock?: never;
+} | {
+    rock: boolean;
+    spin?: never;
+} | {
+    spin?: never;
+    rock?: never;
+}) & {
+    spinSpeed?: number;
+    rockSpeed?: number;
+    height?: number;
+    className?: React.HTMLAttributes<HTMLDivElement>["className"];
+};
+export type ViewerRef = {
+    highlight: (proteinIndex: number, label: string) => Promise<void>;
+    reset: () => Promise<void>;
+    updateSuperposition: (proteinIndex: number, translation?: [number, number, number], rotation?: [
+        [
+            number,
+            number,
+            number
+        ],
+        [
+            number,
+            number,
+            number
+        ],
+        [
+            number,
+            number,
+            number
+        ]
+    ]) => Promise<void>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/react/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,eAAe,EACf,OAAO,EACR,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0CAA0C,CAAC;AAExE,MAAM,MAAM,KAAK,GAAG,EAGnB,GAAG,CACA;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAA;CAAE,GACpC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,CACrC,GAAG;IACA,eAAe,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE3C,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,OAAO,CAAC,EAAE,QAAQ,CAAC;CAIpB,GAAG,CACA;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CACjC,GAAG;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC,WAAW,CAAC,CAAC;CAC/D,CAAC;AAEJ,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,mBAAmB,EAAE,CACnB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE;QACT;YAAC,MAAM;YAAE,MAAM;YAAE,MAAM;SAAC;QACxB;YAAC,MAAM;YAAE,MAAM;YAAE,MAAM;SAAC;QACxB;YAAC,MAAM;YAAE,MAAM;YAAE,MAAM;SAAC;KACzB,KACE,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@e-infra/react-molstar-wrapper",
+  "private": false,
+  "type": "module",
+  "keywords": [
+    "react",
+    "molstar",
+    "typescript"
+  ],
+  "description": "A React wrapper for Mol* (Molstar) molecular visualization library.",
+  "author": {
+    "name": "CERIT-SC"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xcillik/react-molstar-wrapper"
+  },
+  "bugs": {
+    "url": "https://github.com/xcillik/react-molstar-wrapper/issues"
+  },
+  "homepage": "https://github.com/xcillik/react-molstar-wrapper",
+  "maintainers": [
+    "Jakub Čillík <cillik@muni.cz>",
+    "Romana Ďuráčiová <duraciova@mail.muni.cz>",
+    "Michal Mikuš <mikus@ics.muni.cz>"
+  ],
+  "version": "0.0.8",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "dev:showcase": "vite --config vite.config.showcase.ts",
+    "build:showcase": "vite build --config vite.config.showcase.ts",
+    "preview": "vite preview --config vite.config.showcase.ts",
+    "build:lib": "tsc -b && vite build --config vite.config.lib.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,md}\" \"lib/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,md}\" \"lib/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "type:check": "tsc --noEmit",
+    "tsc": "tsc --noEmit --watch",
+    "check": "bun run type:check && bun run lint && bun run format:check"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    },
+    "./style.css": "./dist/react-molstar-wrapper.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.6",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react-swc": "^4.2.2",
+    "typescript": "^5.9.3",
+    "prettier": "3.8.0",
+    "sass-embedded": "^1.93.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "autoprefixer": "^10.4.23",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "typescript-eslint": "^8.46.4",
+    "rollup-preserve-directives": "^1.1.3",
+    "@tailwindcss/vite": "^4.1.18",
+    "ajv": "8.17.1"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "molstar": "^5.4.1",
+    "tailwindcss": "^4.1.18"
+  },
+  "dependencies": {}
+}