@czi-sds/data-viz 2.4.2 → 2.4.3

package/dist/shared/ProteinStructureViewer.cjs.js

@@ -4164,6 +4164,35 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 	};
 }
 //#endregion
+//#region src/core/ProteinStructureViewer/hooks/useSelection.ts
+/**
+* Reconciles the selection the consumer passes with the one the viewer keeps.
+*
+* Selection is controlled when `selection` is passed and owned here when it is
+* not, the same split `useChains` makes for visibility. The camera only ever
+* follows the selection, so without an owner a click on a viewer nobody holds
+* state for would mark the residue and never zoom in on it.
+* `onSelectionChange` fires either way: a consumer that only wants to follow
+* along should not have to take ownership to hear about it.
+*/
+function useSelection({ onSelectionChange, selection, structure }) {
+	const isControlled = selection !== void 0;
+	const [ownSelection, setOwnSelection] = (0, react.useState)(null);
+	const onSelectionChangeRef = (0, react.useRef)(onSelectionChange);
+	onSelectionChangeRef.current = onSelectionChange;
+	(0, react.useEffect)(() => {
+		setOwnSelection(null);
+	}, [structure]);
+	return {
+		changeSelection: (0, react.useCallback)((next) => {
+			var _onSelectionChangeRef;
+			if (!isControlled) setOwnSelection(next);
+			(_onSelectionChangeRef = onSelectionChangeRef.current) === null || _onSelectionChangeRef === void 0 || _onSelectionChangeRef.call(onSelectionChangeRef, next);
+		}, [isControlled]),
+		selection: isControlled ? selection : ownSelection
+	};
+}
+//#endregion
 //#region src/core/ProteinStructureViewer/utils/focusRepresentation.ts
 /**
 * What Mol* draws around a focused selection, as ball-and-stick over the
@@ -4282,10 +4311,11 @@ function focusWithShell(plugin, loci, includeNeighbours, currentShell, pluginRef
 * chains around them instead, in `useChainHighlight`.
 *
 * The click subscription only reports the selection it was given, so a click
-* moves the camera only once the consumer accepts it and echoes it back -
-* which is what the prop being controlled is supposed to mean. Clicking still
-* marks immediately, through Mol*'s own focus behavior, so the structure
-* responds to a click whether or not the consumer wires the prop up.
+* moves the camera only once whoever owns the selection accepts it: the
+* consumer echoing it back when `selection` is controlled, the viewer itself
+* when it is not. Clicking still marks immediately, through Mol*'s own focus
+* behavior, so the structure responds to a click even when a consumer
+* controlling the selection declines it.
 */
 function useSelectionFocus({ hiddenChains, isReady, pluginRef, selection, setClipRatio }) {
 	var _selection$chains, _selection$residues;
@@ -4575,14 +4605,16 @@ function resolveScaleProps(overlay, hasPlddt) {
 * Interactive 3D protein structure viewer built on Mol*, with a sequence panel,
 * pLDDT confidence coloring, per-residue value overlays, and a stats legend.
 *
-* The viewer is controlled for selection: `selectedResidue` drives the camera
-* (clicking a residue zooms in on it, clearing the selection zooms back out),
-* while hover state is owned internally so the legend can show a live readout
-* without the consumer round-tripping every pointer move.
+* The selection drives the camera: clicking a residue zooms in on it, and
+* clearing the selection zooms back out. It is controlled when `selection` is
+* passed and owned internally when it is not, so a click zooms without the
+* consumer holding any state. Hover state is always owned internally, so the
+* legend can show a live readout without the consumer round-tripping every
+* pointer move.
 */
 const ProteinStructureViewer = (0, react.forwardRef)((props, ref) => {
 	var _selection$chains;
-	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, structure, plddt, residueOverlay, selection = null, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = require_objectSpread2._objectWithoutProperties(props, _excluded);
+	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, structure, plddt, residueOverlay, selection: selectionProp, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = require_objectSpread2._objectWithoutProperties(props, _excluded);
 	const theme = (0, _mui_material_styles.useTheme)();
 	const mode = (0, _czi_sds_components.getMode)({ theme });
 	const semanticColors = (0, _czi_sds_components.getSemanticColors)({ theme });
@@ -4610,9 +4642,14 @@ const ProteinStructureViewer = (0, react.forwardRef)((props, ref) => {
 		return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.fillSelected, FALLBACK_HIGHLIGHT_COLOR);
 	}, [semanticColors]);
 	const { handleResidueHover, hoveredResidue } = useResidueHoverState(onResidueHover);
+	const { changeSelection, selection } = useSelection({
+		onSelectionChange,
+		selection: selectionProp,
+		structure
+	});
 	const handleSelectionClear = (0, react.useCallback)(() => {
-		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(null);
-	}, [onSelectionChange]);
+		changeSelection(null);
+	}, [changeSelection]);
 	/**
 	* Chains the selection covers whole, which is what makes a chain caption a
 	* toggle rather than a one-way switch. Keyed on its contents because the
@@ -4632,9 +4669,8 @@ const ProteinStructureViewer = (0, react.forwardRef)((props, ref) => {
 	*/
 	const handleChainSelect = (0, react.useCallback)((chainId) => {
 		var _selection$chains2, _selection$residues;
-		const isOnlyThisChain = (selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length);
-		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(isOnlyThisChain ? null : { chains: [chainId] });
-	}, [onSelectionChange, selection]);
+		changeSelection((selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length) ? null : { chains: [chainId] });
+	}, [changeSelection, selection]);
 	/**
 	* Dims every other chain while a chain's name is pointed at, in the legend
 	* or in the sequence panel's captions, and leaves the selected chain lit
@@ -4673,7 +4709,7 @@ const ProteinStructureViewer = (0, react.forwardRef)((props, ref) => {
 		onChainToggle: toggleChain,
 		onResidueClick,
 		onResidueHover: handleResidueHover,
-		onSelectionChange,
+		onSelectionChange: changeSelection,
 		onSelectionClear: handleSelectionClear,
 		selectedChains,
 		sequenceViewerBackgroundColor,

package/dist/shared/ProteinStructureViewer.esm.js

@@ -4163,6 +4163,35 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 	};
 }
 //#endregion
+//#region src/core/ProteinStructureViewer/hooks/useSelection.ts
+/**
+* Reconciles the selection the consumer passes with the one the viewer keeps.
+*
+* Selection is controlled when `selection` is passed and owned here when it is
+* not, the same split `useChains` makes for visibility. The camera only ever
+* follows the selection, so without an owner a click on a viewer nobody holds
+* state for would mark the residue and never zoom in on it.
+* `onSelectionChange` fires either way: a consumer that only wants to follow
+* along should not have to take ownership to hear about it.
+*/
+function useSelection({ onSelectionChange, selection, structure }) {
+	const isControlled = selection !== void 0;
+	const [ownSelection, setOwnSelection] = useState(null);
+	const onSelectionChangeRef = useRef(onSelectionChange);
+	onSelectionChangeRef.current = onSelectionChange;
+	useEffect(() => {
+		setOwnSelection(null);
+	}, [structure]);
+	return {
+		changeSelection: useCallback((next) => {
+			var _onSelectionChangeRef;
+			if (!isControlled) setOwnSelection(next);
+			(_onSelectionChangeRef = onSelectionChangeRef.current) === null || _onSelectionChangeRef === void 0 || _onSelectionChangeRef.call(onSelectionChangeRef, next);
+		}, [isControlled]),
+		selection: isControlled ? selection : ownSelection
+	};
+}
+//#endregion
 //#region src/core/ProteinStructureViewer/utils/focusRepresentation.ts
 /**
 * What Mol* draws around a focused selection, as ball-and-stick over the
@@ -4281,10 +4310,11 @@ function focusWithShell(plugin, loci, includeNeighbours, currentShell, pluginRef
 * chains around them instead, in `useChainHighlight`.
 *
 * The click subscription only reports the selection it was given, so a click
-* moves the camera only once the consumer accepts it and echoes it back -
-* which is what the prop being controlled is supposed to mean. Clicking still
-* marks immediately, through Mol*'s own focus behavior, so the structure
-* responds to a click whether or not the consumer wires the prop up.
+* moves the camera only once whoever owns the selection accepts it: the
+* consumer echoing it back when `selection` is controlled, the viewer itself
+* when it is not. Clicking still marks immediately, through Mol*'s own focus
+* behavior, so the structure responds to a click even when a consumer
+* controlling the selection declines it.
 */
 function useSelectionFocus({ hiddenChains, isReady, pluginRef, selection, setClipRatio }) {
 	var _selection$chains, _selection$residues;
@@ -4572,7 +4602,7 @@ function resolveScaleProps(overlay, hasPlddt) {
 }
 var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	var _selection$chains;
-	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, structure, plddt, residueOverlay, selection = null, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded);
+	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, structure, plddt, residueOverlay, selection: selectionProp, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded);
 	const theme = useTheme();
 	const mode = getMode({ theme });
 	const semanticColors = getSemanticColors({ theme });
@@ -4600,9 +4630,14 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.fillSelected, FALLBACK_HIGHLIGHT_COLOR);
 	}, [semanticColors]);
 	const { handleResidueHover, hoveredResidue } = useResidueHoverState(onResidueHover);
+	const { changeSelection, selection } = useSelection({
+		onSelectionChange,
+		selection: selectionProp,
+		structure
+	});
 	const handleSelectionClear = useCallback(() => {
-		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(null);
-	}, [onSelectionChange]);
+		changeSelection(null);
+	}, [changeSelection]);
 	/**
 	* Chains the selection covers whole, which is what makes a chain caption a
 	* toggle rather than a one-way switch. Keyed on its contents because the
@@ -4622,9 +4657,8 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	*/
 	const handleChainSelect = useCallback((chainId) => {
 		var _selection$chains2, _selection$residues;
-		const isOnlyThisChain = (selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length);
-		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(isOnlyThisChain ? null : { chains: [chainId] });
-	}, [onSelectionChange, selection]);
+		changeSelection((selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length) ? null : { chains: [chainId] });
+	}, [changeSelection, selection]);
 	/**
 	* Dims every other chain while a chain's name is pointed at, in the legend
 	* or in the sequence panel's captions, and leaves the selected chain lit
@@ -4663,7 +4697,7 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		onChainToggle: toggleChain,
 		onResidueClick,
 		onResidueHover: handleResidueHover,
-		onSelectionChange,
+		onSelectionChange: changeSelection,
 		onSelectionClear: handleSelectionClear,
 		selectedChains,
 		sequenceViewerBackgroundColor,

package/dist/shared/index2.cjs.d.ts

@@ -50,12 +50,12 @@ interface ResidueValueOverlay {
  * address it.
  *
  * `index` is the viewer's own key: the position in `plddt` and in
- * `residueOverlay`'s map, and what `selectedResidue` takes. `chainId`, `seqId`
- * and `insCode` are what the file says, which is what the sequence panel shows
- * and what a system that supplied the structure will recognise. They differ
- * from `index` whenever the file does not number a single chain from 1 -- a
- * crop, or a complex -- so address a residue outside the viewer with those
- * three, not with `index`.
+ * `residueOverlay`'s map, and what `selection.residues` takes. `chainId`,
+ * `seqId` and `insCode` are what the file says, which is what the sequence
+ * panel shows and what a system that supplied the structure will recognise.
+ * They differ from `index` whenever the file does not number a single chain
+ * from 1 -- a crop, or a complex -- so address a residue outside the viewer
+ * with those three, not with `index`.
  *
  * `insCode` is rarely set but is part of the address when it is: `10` and `10A`
  * are different residues on the same chain, so chain and number alone do not
@@ -208,13 +208,15 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
   /** Per-residue values that override pLDDT coloring while set. */
   residueOverlay?: ResidueValueOverlay | null;
   /**
-   * What is selected, or null when nothing is. Controlled: the camera frames
-   * whatever the selection covers, and clearing it zooms back out to the
-   * default view.
+   * What is selected, or null when nothing is. Leave undefined to let the
+   * viewer own the selection, so clicking a residue zooms in on it with no
+   * state on the consumer's side; passing it takes that over, and a click then
+   * moves the camera only once `onSelectionChange` is echoed back here.
    *
-   * Residues are drawn in ball-and-stick over the cartoon; whole chains are
-   * left as they are and the chains around them dim, the same as hovering a
-   * chain's name.
+   * Either way the camera frames whatever the selection covers, and clearing
+   * it zooms back out to the default view. Residues are drawn in
+   * ball-and-stick over the cartoon; whole chains are left as they are and the
+   * chains around them dim, the same as hovering a chain's name.
    */
   selection?: StructureSelection | null;
   /**
@@ -286,6 +288,8 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    *
    * A whole-chain selection arrives as `{ chains: [id] }` rather than as every
    * index on it, so echoing it straight back into `selection` costs nothing.
+   * Fires whether or not `selection` is controlled, so a consumer can follow
+   * the viewer's own selection without owning it.
    */
   onSelectionChange?: (selection: StructureSelection | null) => void;
   /**

package/dist/shared/index2.esm.d.ts

@@ -52,12 +52,12 @@ interface ResidueValueOverlay {
  * address it.
  *
  * `index` is the viewer's own key: the position in `plddt` and in
- * `residueOverlay`'s map, and what `selectedResidue` takes. `chainId`, `seqId`
- * and `insCode` are what the file says, which is what the sequence panel shows
- * and what a system that supplied the structure will recognise. They differ
- * from `index` whenever the file does not number a single chain from 1 -- a
- * crop, or a complex -- so address a residue outside the viewer with those
- * three, not with `index`.
+ * `residueOverlay`'s map, and what `selection.residues` takes. `chainId`,
+ * `seqId` and `insCode` are what the file says, which is what the sequence
+ * panel shows and what a system that supplied the structure will recognise.
+ * They differ from `index` whenever the file does not number a single chain
+ * from 1 -- a crop, or a complex -- so address a residue outside the viewer
+ * with those three, not with `index`.
  *
  * `insCode` is rarely set but is part of the address when it is: `10` and `10A`
  * are different residues on the same chain, so chain and number alone do not
@@ -210,13 +210,15 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
   /** Per-residue values that override pLDDT coloring while set. */
   residueOverlay?: ResidueValueOverlay | null;
   /**
-   * What is selected, or null when nothing is. Controlled: the camera frames
-   * whatever the selection covers, and clearing it zooms back out to the
-   * default view.
+   * What is selected, or null when nothing is. Leave undefined to let the
+   * viewer own the selection, so clicking a residue zooms in on it with no
+   * state on the consumer's side; passing it takes that over, and a click then
+   * moves the camera only once `onSelectionChange` is echoed back here.
    *
-   * Residues are drawn in ball-and-stick over the cartoon; whole chains are
-   * left as they are and the chains around them dim, the same as hovering a
-   * chain's name.
+   * Either way the camera frames whatever the selection covers, and clearing
+   * it zooms back out to the default view. Residues are drawn in
+   * ball-and-stick over the cartoon; whole chains are left as they are and the
+   * chains around them dim, the same as hovering a chain's name.
    */
   selection?: StructureSelection | null;
   /**
@@ -288,6 +290,8 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    *
    * A whole-chain selection arrives as `{ chains: [id] }` rather than as every
    * index on it, so echoing it straight back into `selection` costs nothing.
+   * Fires whether or not `selection` is controlled, so a consumer can follow
+   * the viewer's own selection without owning it.
    */
   onSelectionChange?: (selection: StructureSelection | null) => void;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@czi-sds/data-viz",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "main": "dist/index.cjs.js",
   "types": "dist/index.cjs.d.ts",
   "module": "dist/index.esm.js",
@@ -147,5 +147,5 @@
     "echarts": "^6.0.0",
     "lodash": "^4.17.21"
   },
-  "gitHead": "4fb1150d51f5cde0b88503ca0146eba3b53f1ab1"
+  "gitHead": "52f0027db4ead40a4a311a27aefd762ed8823d47"
 }