pdbe-molstar 3.3.0 → 3.3.2

package/lib/extensions/state-gallery/manager.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StateGalleryManager = void 0;
+exports.StateGalleryManager = exports.ImageCategory = void 0;
 const tslib_1 = require("tslib");
 const camera_1 = require("molstar/lib/mol-canvas3d/camera");
 const linear_algebra_1 = require("molstar/lib/mol-math/linear-algebra");
@@ -11,13 +11,24 @@ const rxjs_1 = require("rxjs");
 const helpers_1 = require("../../helpers");
 const behavior_1 = require("./behavior");
 const config_1 = require("./config");
-const ImageCategory = ['Entry', 'Assemblies', 'Entities', 'Ligands', 'Modified residues', 'Domains', 'Miscellaneous'];
+const titles_1 = require("./titles");
+/** Categories of images/states */
+exports.ImageCategory = ['Entry', 'Assemblies', 'Entities', 'Ligands', 'Modified residues', 'Domains', 'Miscellaneous'];
+/** Provides functionality to get list of images (3D states) for an entry, load individual images, keeps track of the currently loaded image.
+ * Use async `StateGalleryManager.create()` to create an instance. */
 class StateGalleryManager {
-    constructor(plugin, entryId, data, options) {
+    constructor(plugin, 
+    /** Entry identifier, i.e. '1cbs' */
+    entryId, 
+    /** Data retrieved from API */
+    data, 
+    /** Config values */
+    options) {
         this.plugin = plugin;
         this.entryId = entryId;
         this.data = data;
         this.options = options;
+        /** BehaviorSubjects for current state of the manager */
         this.events = {
             /** Image that has been requested to load most recently. */
             requestedImage: new rxjs_1.BehaviorSubject(undefined),
@@ -29,6 +40,7 @@ class StateGalleryManager {
         /** True if at least one image has been loaded (this is to skip animation on the first load) */
         this.firstLoaded = false;
         this.loader = new helpers_1.PreemptiveQueue((filename) => this._load(filename));
+        /** Cache for MOLJ states from API */
         this.cache = {};
         const allImages = listImages(data, true);
         this.images = removeWithSuffixes(allImages, ['_side', '_top']); // removing images in different orientation than 'front'
@@ -41,13 +53,15 @@ class StateGalleryManager {
                 (_c = customState.manager) === null || _c === void 0 ? void 0 : _c.next(this);
         });
         this.events.requestedImage.subscribe(img => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c;
             const customState = (0, behavior_1.StateGalleryCustomState)(this.plugin);
-            (_a = customState.title) === null || _a === void 0 ? void 0 : _a.next((_b = img === null || img === void 0 ? void 0 : img.simple_title) !== null && _b !== void 0 ? _b : img === null || img === void 0 ? void 0 : img.filename);
-            if (((_c = customState.manager) === null || _c === void 0 ? void 0 : _c.value) !== this)
-                (_d = customState.manager) === null || _d === void 0 ? void 0 : _d.next(this);
+            (_a = customState.requestedImage) === null || _a === void 0 ? void 0 : _a.next(img);
+            if (((_b = customState.manager) === null || _b === void 0 ? void 0 : _b.value) !== this)
+                (_c = customState.manager) === null || _c === void 0 ? void 0 : _c.next(this);
         });
     }
+    /** Create an instance of `StateGalleryManager` and retrieve list of images from API.
+     * Options that are not provided will use values from plugin config. */
     static create(plugin, entryId, options) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             const fullOptions = Object.assign(Object.assign({}, (0, config_1.getStateGalleryConfig)(plugin)), options);
@@ -58,6 +72,7 @@ class StateGalleryManager {
             return new this(plugin, entryId, data, fullOptions);
         });
     }
+    /** Load an image (3D state). Do not call directly; use `load` instead, which handles concurrent requests. */
     _load(filename) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             if (!this.plugin.canvas3d)
@@ -82,6 +97,7 @@ class StateGalleryManager {
             this.firstLoaded = true;
         });
     }
+    /** Request to load an image (3D state). When there are multiple concurrent requests, some requests may be skipped (will resolve to `{ status: 'cancelled' }` or `{ status: 'skipped' }`) as only the last request is really important. */
     load(img) {
         var _a;
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -108,6 +124,7 @@ class StateGalleryManager {
             }
         });
     }
+    /** Move to next/previous image in the list. */
     shift(shift) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             const current = this.events.requestedImage.value;
@@ -117,16 +134,19 @@ class StateGalleryManager {
             return yield this.load(this.images[iNew]);
         });
     }
+    /** Request to load the previous image in the list */
     loadPrevious() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return yield this.shift(-1);
         });
     }
+    /** Request to load the next image in the list */
     loadNext() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return yield this.shift(1);
         });
     }
+    /** Fetch a MOLJ state from API */
     fetchSnapshot(filename) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             const url = (0, helpers_1.combineUrl)(this.options.ServerUrl, `${filename}.molj`);
@@ -134,6 +154,7 @@ class StateGalleryManager {
             return data;
         });
     }
+    /** Get MOLJ state for the image (get from cache or fetch from API) */
     getSnapshot(filename) {
         var _a;
         var _b;
@@ -141,6 +162,7 @@ class StateGalleryManager {
             return (_a = (_b = this.cache)[filename]) !== null && _a !== void 0 ? _a : (_b[filename] = yield this.fetchSnapshot(filename));
         });
     }
+    /** Get full image information based on filename. Return `undefined` if image with given filename is not in the list. */
     getImageByFilename(filename) {
         const index = this.filenameIndex.get(filename);
         if (index === undefined)
@@ -149,6 +171,7 @@ class StateGalleryManager {
     }
 }
 exports.StateGalleryManager = StateGalleryManager;
+/** Get the list of images, captions etc. for an entry from API */
 function getData(plugin, serverUrl, entryId) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         const url = (0, helpers_1.combineUrl)(serverUrl, entryId + '.json');
@@ -168,62 +191,52 @@ function listImages(data, byCategory = false) {
         const out = [];
         // Entry
         for (const img of (_c = (_b = (_a = data === null || data === void 0 ? void 0 : data.entry) === null || _a === void 0 ? void 0 : _a.all) === null || _b === void 0 ? void 0 : _b.image) !== null && _c !== void 0 ? _c : []) {
-            const title = img.filename.includes('_chemically_distinct_molecules')
-                ? 'Deposited model (color by entity)'
-                : img.filename.includes('_chain')
-                    ? 'Deposited model (color by chain)'
-                    : undefined;
-            out.push(Object.assign(Object.assign({}, img), { category: 'Entry', simple_title: title }));
+            out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Entry' }), titles_1.ImageTitles.entry(img)));
         }
         // Validation
         for (const img of (_g = (_f = (_e = (_d = data === null || data === void 0 ? void 0 : data.validation) === null || _d === void 0 ? void 0 : _d.geometry) === null || _e === void 0 ? void 0 : _e.deposited) === null || _f === void 0 ? void 0 : _f.image) !== null && _g !== void 0 ? _g : []) {
-            out.push(Object.assign(Object.assign({}, img), { category: 'Entry', simple_title: 'Geometry validation' }));
+            out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Entry' }), titles_1.ImageTitles.validation(img)));
         }
         // Bfactor
         for (const img of (_k = (_j = (_h = data === null || data === void 0 ? void 0 : data.entry) === null || _h === void 0 ? void 0 : _h.bfactor) === null || _j === void 0 ? void 0 : _j.image) !== null && _k !== void 0 ? _k : []) {
-            out.push(Object.assign(Object.assign({}, img), { category: 'Entry', simple_title: 'B-factor' }));
+            out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Entry' }), titles_1.ImageTitles.bfactor(img)));
         }
         // Assembly
         const assemblies = data === null || data === void 0 ? void 0 : data.assembly;
-        for (const ass in assemblies) {
-            for (const img of (_l = assemblies[ass].image) !== null && _l !== void 0 ? _l : []) {
-                const title = img.filename.includes('_chemically_distinct_molecules')
-                    ? `Assembly ${ass} (color by entity)`
-                    : img.filename.includes('_chain')
-                        ? `Assembly ${ass} (color by chain)`
-                        : undefined;
-                out.push(Object.assign(Object.assign({}, img), { category: 'Assemblies', simple_title: title }));
+        for (const assemblyId in assemblies) {
+            for (const img of (_l = assemblies[assemblyId].image) !== null && _l !== void 0 ? _l : []) {
+                out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Assemblies' }), titles_1.ImageTitles.assembly(img, { assemblyId })));
             }
         }
         // Entity
         const entities = data === null || data === void 0 ? void 0 : data.entity;
-        for (const entity in entities) {
-            for (const img of (_m = entities[entity].image) !== null && _m !== void 0 ? _m : []) {
-                out.push(Object.assign(Object.assign({}, img), { category: 'Entities', simple_title: `Entity ${entity}` }));
+        for (const entityId in entities) {
+            for (const img of (_m = entities[entityId].image) !== null && _m !== void 0 ? _m : []) {
+                out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Entities' }), titles_1.ImageTitles.entity(img, { entityId })));
             }
         }
         // Ligand
         const ligands = (_o = data === null || data === void 0 ? void 0 : data.entry) === null || _o === void 0 ? void 0 : _o.ligands;
-        for (const ligand in ligands) {
-            for (const img of (_p = ligands[ligand].image) !== null && _p !== void 0 ? _p : []) {
-                out.push(Object.assign(Object.assign({}, img), { category: 'Ligands', simple_title: `Ligand environment for ${ligand}` }));
+        for (const compId in ligands) {
+            for (const img of (_p = ligands[compId].image) !== null && _p !== void 0 ? _p : []) {
+                out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Ligands' }), titles_1.ImageTitles.ligand(img, { compId })));
             }
         }
         // Modres
         const modres = (_q = data === null || data === void 0 ? void 0 : data.entry) === null || _q === void 0 ? void 0 : _q.mod_res;
-        for (const res in modres) {
-            for (const img of (_r = modres[res].image) !== null && _r !== void 0 ? _r : []) {
-                out.push(Object.assign(Object.assign({}, img), { category: 'Modified residues', simple_title: `Modified residue ${res}` }));
+        for (const compId in modres) {
+            for (const img of (_r = modres[compId].image) !== null && _r !== void 0 ? _r : []) {
+                out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Modified residues' }), titles_1.ImageTitles.modres(img, { compId })));
             }
         }
         // Domain
-        for (const entity in entities) {
-            const dbs = entities[entity].database;
+        for (const entityId in entities) {
+            const dbs = entities[entityId].database;
             for (const db in dbs) {
                 const domains = dbs[db];
-                for (const domain in domains) {
-                    for (const img of (_s = domains[domain].image) !== null && _s !== void 0 ? _s : []) {
-                        out.push(Object.assign(Object.assign({}, img), { category: 'Domains', simple_title: `${db} ${domain} (entity ${entity})` }));
+                for (const familyId in domains) {
+                    for (const img of (_s = domains[familyId].image) !== null && _s !== void 0 ? _s : []) {
+                        out.push(Object.assign(Object.assign(Object.assign({}, img), { category: 'Domains' }), titles_1.ImageTitles.domain(img, { db, familyId, entityId })));
                     }
                 }
             }
@@ -250,6 +263,7 @@ function pushImages(out, data) {
     }
     return out;
 }
+/** Return a filtered list of images, removing all images with filename ending in one of `suffixes` */
 function removeWithSuffixes(images, suffixes) {
     return images.filter(img => !suffixes.some(suffix => img.filename.endsWith(suffix)));
 }
@@ -278,12 +292,15 @@ function getCameraFromSnapshot(snapshot) {
     const json = JSON.parse(snapshot);
     return (_d = (_c = (_b = (_a = json === null || json === void 0 ? void 0 : json.entries) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.snapshot) === null || _c === void 0 ? void 0 : _c.camera) === null || _d === void 0 ? void 0 : _d.current;
 }
+/** Recalculate camera distance from target in `snapshot` based on `snapshot.radius`,
+ * keeping target, direction, and up from snapshot but using camera mode and FOV from `camera`. */
 function refocusCameraSnapshot(camera, snapshot) {
     if (snapshot === undefined)
         return undefined;
     const dir = linear_algebra_1.Vec3.sub((0, linear_algebra_1.Vec3)(), snapshot.target, snapshot.position);
     return camera.getInvariantFocus(snapshot.target, snapshot.radius, snapshot.up, dir);
 }
+/** Get current camera positioning */
 function getCurrentCamera(plugin) {
     if (!plugin.canvas3d)
         return camera_1.Camera.createDefaultSnapshot();

package/lib/extensions/state-gallery/titles.d.ts

@@ -0,0 +1,26 @@
+import { Image } from './manager';
+type Titles = Pick<Image, 'title' | 'subtitle'>;
+/** Functions for creating informative image (3D state) titles for display in UI */
+export declare const ImageTitles: {
+    entry(img: Image): Titles;
+    validation(img: Image): Titles;
+    bfactor(img: Image): Titles;
+    assembly(img: Image, info: {
+        assemblyId: string;
+    }): Titles;
+    entity(img: Image, info: {
+        entityId: string;
+    }): Titles;
+    ligand(img: Image, info: {
+        compId: string;
+    }): Titles;
+    modres(img: Image, info: {
+        compId: string;
+    }): Titles;
+    domain(img: Image, info: {
+        db: string;
+        familyId: string;
+        entityId: string;
+    }): Titles;
+};
+export {};

package/lib/extensions/state-gallery/titles.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageTitles = void 0;
+/** Functions for creating informative image (3D state) titles for display in UI */
+exports.ImageTitles = {
+    entry(img) {
+        if (img.filename.includes('_chemically_distinct_molecules')) {
+            return { title: 'Deposited model (color by entity)' };
+        }
+        if (img.filename.includes('_chain')) {
+            return { title: 'Deposited model (color by chain)' };
+        }
+        return {};
+    },
+    validation(img) {
+        return { title: 'Geometry validation' };
+    },
+    bfactor(img) {
+        return { title: 'B-factor' };
+    },
+    assembly(img, info) {
+        if (img.filename.includes('_chemically_distinct_molecules')) {
+            return { title: `Assembly ${info.assemblyId} (color by entity)` };
+        }
+        if (img.filename.includes('_chain')) {
+            return { title: `Assembly ${info.assemblyId} (color by chain)` };
+        }
+        return {};
+    },
+    entity(img, info) {
+        const entityName = getSpans(img.description)[1];
+        return {
+            title: `Entity ${info.entityId}`,
+            subtitle: entityName,
+        };
+    },
+    ligand(img, info) {
+        const ligandName = getParenthesis(getSpans(img.description)[0]);
+        return {
+            title: `Ligand environment for ${info.compId}`,
+            subtitle: ligandName,
+        };
+    },
+    modres(img, info) {
+        const modresName = getParenthesis(getSpans(img.description)[1]);
+        return {
+            title: `Modified residue ${info.compId}`,
+            subtitle: modresName,
+        };
+    },
+    domain(img, info) {
+        const familyName = getParenthesis(getSpans(img.description)[1]);
+        return {
+            title: `${info.db} ${info.familyId} (entity ${info.entityId})`,
+            subtitle: familyName,
+        };
+    },
+};
+/** Get contents of `<span ...>...</span>` tags from an HTML string */
+function getSpans(text) {
+    const matches = (text !== null && text !== void 0 ? text : '').matchAll(/<span [^>]*>([^<]*)<\/span>/g);
+    return Array.from(matches).map(match => match[1]);
+}
+/** Get content of parenthesis (`(...)`) from a string */
+function getParenthesis(text) {
+    var _a;
+    return (_a = text === null || text === void 0 ? void 0 : text.match(/\((.*)\)/)) === null || _a === void 0 ? void 0 : _a[1];
+}

package/lib/extensions/state-gallery/ui.d.ts

@@ -1,10 +1,14 @@
 import { CollapsableControls, CollapsableState } from 'molstar/lib/mol-plugin-ui/base';
 import React from 'react';
 import { StateGalleryManager } from './manager';
+/** React state for `StateGalleryControls` */
 interface StateGalleryControlsState {
+    /** Content of "Entry ID" text field */
     entryId: string;
     manager: StateGalleryManager | undefined;
+    /** `true` when initializing manager (fetching list of images) */
     isLoading: boolean;
+    /** Mirrors `this.plugin.behaviors.state.isBusy` (`true` when loading a specific image) */
     isBusy: boolean;
 }
 /** "3D State Gallery" section in Structure Tools (right panel) */
@@ -12,12 +16,16 @@ export declare class StateGalleryControls extends CollapsableControls<{}, StateG
     protected defaultState(): StateGalleryControlsState & CollapsableState;
     componentDidMount(): void;
     private get values();
-    private setEntryId;
-    private load;
     private onChangeValues;
+    /** Load entry given by `this.state.entryId` */
+    private load;
     private loadDisabled;
     protected renderControls(): React.JSX.Element | null;
 }
-/** Box in viewport with state title and arrows to move between states */
+/** Part of "3D State Gallery" section related to a specific entry */
+export declare function StateGalleryManagerControls(props: {
+    manager: StateGalleryManager;
+}): import("react/jsx-runtime").JSX.Element;
+/** Box in viewport with image title and arrows to move between images (3D states) */
 export declare function StateGalleryTitleBox(): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/lib/extensions/state-gallery/ui.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StateGalleryTitleBox = exports.StateGalleryControls = void 0;
+exports.StateGalleryTitleBox = exports.StateGalleryManagerControls = exports.StateGalleryControls = void 0;
 const tslib_1 = require("tslib");
 const jsx_runtime_1 = require("react/jsx-runtime");
 const base_1 = require("molstar/lib/mol-plugin-ui/base");
@@ -13,18 +13,18 @@ const helpers_1 = require("../../helpers");
 const icons_2 = require("../../ui/icons");
 const behavior_1 = require("./behavior");
 const manager_1 = require("./manager");
+/** Parameter definition for ParameterControls part of "3D State Gallery" section */
 const Params = {
-    entryId: param_definition_1.ParamDefinition.Text(),
+    entryId: param_definition_1.ParamDefinition.Text(undefined, { label: 'Entry ID' }),
 };
 /** "3D State Gallery" section in Structure Tools (right panel) */
 class StateGalleryControls extends base_1.CollapsableControls {
     constructor() {
         super(...arguments);
-        this.setEntryId = (entryId) => {
-            this.setState(old => ({
-                entryId,
-            }));
+        this.onChangeValues = (values) => {
+            this.setState({ entryId: values.entryId });
         };
+        /** Load entry given by `this.state.entryId` */
         this.load = () => tslib_1.__awaiter(this, void 0, void 0, function* () {
             if (this.loadDisabled())
                 return;
@@ -32,9 +32,6 @@ class StateGalleryControls extends base_1.CollapsableControls {
             const manager = yield manager_1.StateGalleryManager.create(this.plugin, this.state.entryId);
             this.setState({ manager, isLoading: false, description: this.state.entryId.toUpperCase() });
         });
-        this.onChangeValues = (values) => {
-            this.setEntryId(values.entryId);
-        };
         this.loadDisabled = () => { var _a; return !this.state.entryId || this.state.entryId === ((_a = this.state.manager) === null || _a === void 0 ? void 0 : _a.entryId) || this.state.isBusy || this.state.isLoading; };
     }
     defaultState() {
@@ -59,7 +56,7 @@ class StateGalleryControls extends base_1.CollapsableControls {
             if (this.state.entryId === '' && sel.structures.length > 0) {
                 const id = (_a = sel.structures[0].cell.obj) === null || _a === void 0 ? void 0 : _a.data.model.entryId;
                 if (id) {
-                    this.setEntryId(id.toLowerCase());
+                    this.setState({ entryId: id.toLowerCase() });
                 }
             }
         });
@@ -73,11 +70,12 @@ class StateGalleryControls extends base_1.CollapsableControls {
     renderControls() {
         return (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(parameters_1.ParameterControls, { params: Params, values: this.values, onChangeValues: this.onChangeValues, onEnter: this.load }), (!this.state.manager || this.state.manager.entryId !== this.state.entryId) &&
                     (0, jsx_runtime_1.jsx)(common_1.Button, Object.assign({ icon: this.state.isLoading ? undefined : icons_1.CheckSvg, title: 'Load', disabled: this.loadDisabled(), onClick: this.load, className: 'msp-btn-block' }, { children: this.state.isLoading ? 'Loading...' : 'Load' })), this.state.manager &&
-                    (0, jsx_runtime_1.jsx)(ManagerControls, { manager: this.state.manager })] });
+                    (0, jsx_runtime_1.jsx)(StateGalleryManagerControls, { manager: this.state.manager })] });
     }
 }
 exports.StateGalleryControls = StateGalleryControls;
-function ManagerControls(props) {
+/** Part of "3D State Gallery" section related to a specific entry */
+function StateGalleryManagerControls(props) {
     var _a;
     const images = props.manager.images;
     const nImages = images.length;
@@ -108,21 +106,23 @@ function ManagerControls(props) {
     }
     return (0, jsx_runtime_1.jsxs)("div", Object.assign({ className: 'pdbemolstar-state-gallery-controls', onKeyDown: handleKeyDown, tabIndex: -1, ref: keyDownTargetRef }, { children: [(0, jsx_runtime_1.jsx)(common_1.ExpandGroup, Object.assign({ header: 'States', initiallyExpanded: true }, { children: (0, jsx_runtime_1.jsx)("div", Object.assign({ style: { marginBottom: 8 } }, { children: categories.groups.map(cat => {
                         var _a;
-                        return (0, jsx_runtime_1.jsx)(common_1.ExpandGroup, Object.assign({ header: cat, initiallyExpanded: true }, { children: (_a = categories.members.get(cat)) === null || _a === void 0 ? void 0 : _a.map(img => (0, jsx_runtime_1.jsx)(StateButton, { img: img, isSelected: img === selected, status: status, onClick: () => props.manager.load(img) }, img.filename)) }), cat);
+                        return (0, jsx_runtime_1.jsx)(common_1.ExpandGroup, Object.assign({ header: cat, initiallyExpanded: true }, { children: (_a = categories.members.get(cat)) === null || _a === void 0 ? void 0 : _a.map(img => (0, jsx_runtime_1.jsx)(ImageButton, { img: img, isSelected: img === selected, status: status, onClick: () => props.manager.load(img) }, img.filename)) }), cat);
                     }) })) }), 'states'), (0, jsx_runtime_1.jsx)(common_1.ExpandGroup, Object.assign({ header: 'Description', initiallyExpanded: true }, { children: (0, jsx_runtime_1.jsx)("div", Object.assign({ className: 'pdbemolstar-state-gallery-legend' }, { children: (0, jsx_runtime_1.jsx)("div", { dangerouslySetInnerHTML: { __html: (_a = selected === null || selected === void 0 ? void 0 : selected.description) !== null && _a !== void 0 ? _a : '' } }) })) }), 'description')] }));
 }
-function StateButton(props) {
+exports.StateGalleryManagerControls = StateGalleryManagerControls;
+/** Button with image title */
+function ImageButton(props) {
     var _a;
     const { img, isSelected, status, onClick } = props;
     const icon = !isSelected ? icons_2.EmptyIconSvg : (status === 'loading') ? icons_2.HourglassBottomSvg : (status === 'error') ? icons_1.ErrorSvg : icons_1.CheckSvg;
-    const title = (_a = img.simple_title) !== null && _a !== void 0 ? _a : img.filename;
-    const errorMsg = (isSelected && status === 'error') ? '[Failed to load] ' : '';
-    return (0, jsx_runtime_1.jsx)(common_1.Button, Object.assign({ className: 'msp-action-menu-button pdbemolstar-state-gallery-state-button', icon: icon, onClick: onClick, title: `${errorMsg}${title}`, style: { fontWeight: isSelected ? 'bold' : undefined } }, { children: title }));
+    const tooltip = imageTooltip(img, isSelected ? status : 'ready');
+    return (0, jsx_runtime_1.jsxs)(common_1.Button, Object.assign({ className: 'msp-action-menu-button pdbemolstar-state-gallery-state-button', icon: icon, onClick: onClick, title: tooltip, style: { fontWeight: isSelected ? 'bold' : undefined } }, { children: [(_a = img.title) !== null && _a !== void 0 ? _a : img.filename, img.subtitle && (0, jsx_runtime_1.jsxs)("small", { children: ["\u2002 ", img.subtitle] })] }));
 }
-/** Box in viewport with state title and arrows to move between states */
+/** Box in viewport with image title and arrows to move between images (3D states) */
 function StateGalleryTitleBox() {
+    var _a;
     const plugin = react_1.default.useContext(base_1.PluginReactContext);
-    const [title, setTitle] = react_1.default.useState(undefined);
+    const [image, setImage] = react_1.default.useState(undefined);
     const [manager, setManager] = react_1.default.useState(undefined);
     const [status, setStatus] = react_1.default.useState('ready');
     const loadingCounter = (0, react_1.useRef)(0);
@@ -130,8 +130,8 @@ function StateGalleryTitleBox() {
         var _a, _b, _c;
         const customState = (0, behavior_1.StateGalleryCustomState)(plugin);
         const subs = [
-            (_a = customState.title) === null || _a === void 0 ? void 0 : _a.subscribe(x => setTitle(x)),
-            (_b = customState.manager) === null || _b === void 0 ? void 0 : _b.subscribe(x => setManager(x)),
+            (_a = customState.requestedImage) === null || _a === void 0 ? void 0 : _a.subscribe(img => setImage(img)),
+            (_b = customState.manager) === null || _b === void 0 ? void 0 : _b.subscribe(mgr => setManager(mgr)),
             (_c = customState.status) === null || _c === void 0 ? void 0 : _c.subscribe(status => {
                 const counter = ++loadingCounter.current;
                 if (status === 'loading') {
@@ -145,10 +145,18 @@ function StateGalleryTitleBox() {
         ];
         return () => subs.forEach(sub => sub === null || sub === void 0 ? void 0 : sub.unsubscribe());
     }, [plugin]);
-    if (title === undefined)
+    if (image === undefined)
         return null;
     return (0, jsx_runtime_1.jsxs)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title-box' }, { children: [manager &&
-                (0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(common_1.Button, { className: 'msp-btn-icon', title: 'Previous state', icon: icons_2.ChevronLeftSvg, onClick: () => manager.loadPrevious() }) }), (0, jsx_runtime_1.jsxs)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title', title: status === 'error' ? `${title} (failed to load)` : status === 'loading' ? `${title} (loading)` : title }, { children: [(0, jsx_runtime_1.jsx)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title-icon' }, { children: (0, jsx_runtime_1.jsx)(icons_1.Icon, { svg: status === 'error' ? icons_1.ErrorSvg : status === 'loading' ? icons_2.HourglassBottomSvg : icons_2.EmptyIconSvg }) })), (0, jsx_runtime_1.jsx)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title-text' }, { children: title }))] })), manager &&
+                (0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(common_1.Button, { className: 'msp-btn-icon', title: 'Previous state', icon: icons_2.ChevronLeftSvg, onClick: () => manager.loadPrevious() }) }), (0, jsx_runtime_1.jsxs)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title', title: imageTooltip(image, status) }, { children: [(0, jsx_runtime_1.jsx)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title-icon' }, { children: (0, jsx_runtime_1.jsx)(icons_1.Icon, { svg: status === 'error' ? icons_1.ErrorSvg : status === 'loading' ? icons_2.HourglassBottomSvg : icons_2.EmptyIconSvg }) })), (0, jsx_runtime_1.jsxs)("div", Object.assign({ className: 'pdbemolstar-state-gallery-title-text' }, { children: [(_a = image.title) !== null && _a !== void 0 ? _a : image.filename, (0, jsx_runtime_1.jsx)("br", {}), (0, jsx_runtime_1.jsx)("small", { children: image.subtitle })] }))] })), manager &&
                 (0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(common_1.Button, { className: 'msp-btn-icon', title: 'Next state', icon: icons_2.ChevronRightSvg, onClick: () => manager === null || manager === void 0 ? void 0 : manager.loadNext() }) })] }));
 }
 exports.StateGalleryTitleBox = StateGalleryTitleBox;
+/** Return tooltip text for an image */
+function imageTooltip(img, status) {
+    var _a;
+    const tooltip = (status === 'error' ? '[Failed to load] \n' : status === 'loading' ? '[Loading] \n' : '')
+        + ((_a = img.title) !== null && _a !== void 0 ? _a : img.filename)
+        + (img.subtitle ? `: ${img.subtitle}` : '');
+    return tooltip;
+}

package/lib/helpers.d.ts

@@ -179,12 +179,13 @@ export declare class PreemptiveQueue<X, Y> {
     /** Request handling loop. Resolves when there are no more requests. Not to be awaited, should run in the background.  */
     private handleRequests;
 }
+/** Functions for working with plugin config items */
 export declare namespace PluginConfigUtils {
-    type ConfigFor<T> = {
+    /** Type of config definition for given type of config values T */
+    type ConfigFor<T extends object> = {
         [key in keyof T]: PluginConfigItem<T[key]>;
     };
-    function getConfigValues<T>(plugin: PluginContext | undefined, configItems: {
-        [name in keyof T]: PluginConfigItem<T[name]>;
-    }, defaults: T): T;
+    /** Retrieve config values for items in `configItems` from the current plugin config */
+    function getConfigValues<T extends object>(plugin: PluginContext | undefined, configItems: ConfigFor<T>, defaults: T): T;
 }
 export {};

package/lib/helpers.js

@@ -507,8 +507,10 @@ class PreemptiveQueue {
     }
 }
 exports.PreemptiveQueue = PreemptiveQueue;
+/** Functions for working with plugin config items */
 var PluginConfigUtils;
 (function (PluginConfigUtils) {
+    /** Retrieve config values for items in `configItems` from the current plugin config */
     function getConfigValues(plugin, configItems, defaults) {
         var _a;
         const values = {};

package/lib/plugin-custom-state.d.ts

@@ -59,9 +59,11 @@ export interface PluginCustomState {
         };
     };
     superpositionError?: string;
+    /** Space for extensions to save their plugin-bound custom state. Only access via `ExtensionCustomState`! */
     extensions?: {
         [extensionId: string]: {} | undefined;
     };
+    /** Registry for custom UI components. Only access via `PluginCustomControls`! */
     customControls?: {
         [region in PluginCustomControlRegion]?: PluginCustomControlRegistry;
     };
@@ -83,9 +85,15 @@ export interface Segment {
 /** Access `plugin.customState` only through this function to get proper typing.
  * Supports getting and setting properties. */
 export declare function PluginCustomState(plugin: PluginContext): PluginCustomState;
-export declare function getExtensionCustomState<T extends {}>(plugin: PluginContext, extensionId: string): Partial<T>;
-export declare function clearExtensionCustomState(plugin: PluginContext, extensionId: string): void;
-export declare function extensionCustomStateGetter<StateType extends {}>(extensionId: string): (plugin: PluginContext) => Partial<StateType>;
+/** Functions for accessing plugin-bound custom state for extensions. */
+export declare const ExtensionCustomState: {
+    /** Get plugin-bound custom state for a specific extension. If not present, initialize with empty object. */
+    get<T extends {}>(plugin: PluginContext, extensionId: string): Partial<T>;
+    /** Remove plugin-bound custom state for a specific extension (if present). */
+    clear(plugin: PluginContext, extensionId: string): void;
+    /** Return function which gets plugin-bound custom state for a specific extension. */
+    getter<StateType extends {}>(extensionId: string): (plugin: PluginContext) => Partial<StateType>;
+};
 /** UI region where custom controls can be registered */
 export type PluginCustomControlRegion = 'structure-tools' | 'viewport-top-center' | 'viewport-top-left';
 /** Collection of registered custom controls in a UI region */

package/lib/plugin-custom-state.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PluginCustomControls = exports.extensionCustomStateGetter = exports.clearExtensionCustomState = exports.getExtensionCustomState = exports.PluginCustomState = void 0;
+exports.PluginCustomControls = exports.ExtensionCustomState = exports.PluginCustomState = void 0;
 ;
 ;
 /** Access `plugin.customState` only through this function to get proper typing.
@@ -10,25 +10,28 @@ function PluginCustomState(plugin) {
     return (_a = plugin.customState) !== null && _a !== void 0 ? _a : (plugin.customState = {});
 }
 exports.PluginCustomState = PluginCustomState;
-function getExtensionCustomState(plugin, extensionId) {
-    var _a, _b;
-    var _c;
-    const extensionStates = (_a = (_c = PluginCustomState(plugin)).extensions) !== null && _a !== void 0 ? _a : (_c.extensions = {});
-    const extensionState = (_b = extensionStates[extensionId]) !== null && _b !== void 0 ? _b : (extensionStates[extensionId] = {});
-    return extensionState;
-}
-exports.getExtensionCustomState = getExtensionCustomState;
-function clearExtensionCustomState(plugin, extensionId) {
-    var _a;
-    var _b;
-    const extensionStates = (_a = (_b = PluginCustomState(plugin)).extensions) !== null && _a !== void 0 ? _a : (_b.extensions = {});
-    delete extensionStates[extensionId];
-}
-exports.clearExtensionCustomState = clearExtensionCustomState;
-function extensionCustomStateGetter(extensionId) {
-    return (plugin) => getExtensionCustomState(plugin, extensionId);
-}
-exports.extensionCustomStateGetter = extensionCustomStateGetter;
+/** Functions for accessing plugin-bound custom state for extensions. */
+exports.ExtensionCustomState = {
+    /** Get plugin-bound custom state for a specific extension. If not present, initialize with empty object. */
+    get(plugin, extensionId) {
+        var _a, _b;
+        var _c;
+        const extensionStates = (_a = (_c = PluginCustomState(plugin)).extensions) !== null && _a !== void 0 ? _a : (_c.extensions = {});
+        const extensionState = (_b = extensionStates[extensionId]) !== null && _b !== void 0 ? _b : (extensionStates[extensionId] = {});
+        return extensionState;
+    },
+    /** Remove plugin-bound custom state for a specific extension (if present). */
+    clear(plugin, extensionId) {
+        var _a;
+        var _b;
+        const extensionStates = (_a = (_b = PluginCustomState(plugin)).extensions) !== null && _a !== void 0 ? _a : (_b.extensions = {});
+        delete extensionStates[extensionId];
+    },
+    /** Return function which gets plugin-bound custom state for a specific extension. */
+    getter(extensionId) {
+        return (plugin) => this.get(plugin, extensionId);
+    },
+};
 /** Functions for registering/unregistering custom UI controls */
 exports.PluginCustomControls = {
     /** Get custom controls in the specified UI `region`. */

package/lib/spec.d.ts

@@ -77,7 +77,9 @@ export interface InitParams {
     };
     /** Display 3D State Gallery */
     galleryView: boolean;
-    /** Leave `undefined` to keep both cartoon and ball-and-sticks based on component type */
+    /** Set default visual style.
+     * Leave undefined to use default visual styles for each component type (polymer, ligand etc.).
+     * Use a `VisualStylesSpec` object to define more detailed visual styles for individual component types, e.g. `{polymer: {type: 'putty', size: 'uniform'}, ligand: 'ball-and-stick'}` */
     visualStyle?: VisualStylesSpec;
     /** Molstar renders multiple visuals (polymer, ligand, water...) visuals by default. This option is to exclude any of these default visuals */
     hideStructure: ('polymer' | 'het' | 'water' | 'carbs' | 'nonStandard' | 'coarse')[];