- implement previewCitationCluster(), restoreProcessorState(), new "bibchange" flag in processCitationCluster() output, and new opt.sort_citations flag in word processor integration

- upgrade to citeproc-js 1.0.29

From Frank's 1.0.25 announcement:

 Provide new command, previewCitationCluster(), that returns
 string for hypothetical citation at specified position,
 without affecting processor state.

 Fix bug that would have cause appendCitationCluster() to
 run updateItems() unnecessarily.

 Provide for forced generation of citationID, for internal use
 in previewing.

From Frank's 1.0.26 announcement:

 Implement new command restoreProcessorState(), for use in,
 er, restoring the processor state, when position variables
 and citation sort keys are already known.

From Frank's 1.0.27 announcement:

 This fixes a couple of obvious problems in the code of the new
 restoreProcessorState() command.

From Frank's 1.0.28 announcement:

 This version introduces a significant change to the return
 value of processCitationCluster().  It is now an array with
 two elements, the first being a JS object that serves as a
 data segment, and the second the list of two-element arrays
 representing insertion indexes and strings for insertion
 (as previously documented).  An API change of this scale
 probably calls for some more visible sign in the version
 numbering, but the original statement on versioning says
 that the major and minor numbers will align with the CSL
 schema, so we stay at level 1.0.

 The data segment referred to above contains just one element
 currently, "bibchange", which is true if processing the
 citation results in any change affecting the bibliography.

 This release also introduces one change and one addition to
 style configuration flags.  The flag at citation.opt["citation-number-sort"]
 has been moved to opt.citation_number_sort, for clarity and
 consistency.  A new flag, opt.sort_citations, is true if
 citations are sorted by the style in any way.

From Frank's 1.0.29 announcement:

 Complete reimplementation of cite-level disambiguation.
 The new code is more compact and maintainable, and
 avoids thrashing behavior that afflicted the previous
 code when a large number of cites required both
 add-names and year-suffix disambiguation.

 Suppress year suffix when fresh ambig keys are generated.
 Inserts by a plugin affecting year suffixes should now be
 correctly handled.

chrome/content/zotero/integration/addCitationDialog.js

@@ -547,21 +547,25 @@ var Zotero_Citation_Dialog = new function () {
 		} else {
 			var items = itemsView.getSelectedItems(true); // treeview from selectItemsDialog.js
 			
-			var citationItem = {};
-			citationItem.id = items[0];
-			for(var property in _preserveData) {
-				if(property == "label") {
-					citationItem[property] = _locatorNameArray[document.getElementById(property).selectedIndex];
-				} else {
-					citationItem[property] = document.getElementById(property)[_preserveData[property]];
+			if(items.length) {
+				var citationItem = {};
+				citationItem.id = items[0];
+				for(var property in _preserveData) {
+					if(property == "label") {
+						citationItem[property] = _locatorNameArray[document.getElementById(property).selectedIndex];
+					} else {
+						citationItem[property] = document.getElementById(property)[_preserveData[property]];
+					}
 				}
+				
+				if(citationItem["locator"] == "") {
+					citationItem["locator"] = citationItem["label"] = undefined;
+				}
+				
+				io.citation.citationItems = [citationItem];
+			} else {
+				io.citation.citationItems = [];
 			}
-			
-			if(citationItem["locator"] == "") {
-				citationItem["locator"] = citationItem["label"] = undefined;
-			}
-			
-			io.citation.citationItems = [citationItem];
 		}
 	}
 	

chrome/content/zotero/xpcom/integration.js

@@ -584,7 +584,7 @@ Zotero.Integration.Document.prototype._updateSession = function(newField, editFi
 	
 	// if we are reloading this session, assume no item IDs to be updated except for edited items
 	if(this._reloadSession) {
-		this._session.updateCitations();
+		this._session.restoreProcessorState();
 		this._session.updateIndices = {};
 		this._session.updateItemIDs = {};
 		this._session.bibliographyHasChanged = false;
@@ -1300,37 +1300,43 @@ Zotero.Integration.Session.prototype.updateUpdateIndices = function(regenerateAl
 	}
 }
 
+/**
+ * Returns citations before and after a given index
+ */
+Zotero.Integration.Session.prototype._getPrePost = function(index) {
+	var citationIndices = [];
+	var citationsPre = [];
+	for(var i=0; i<index; i++) {
+		if(this.citationsByIndex[i] && !this.newIndices[i] && !this.citationsByIndex[i].properties.delete) {
+			citationsPre.push([this.citationsByIndex[i].citationID, this.citationsByIndex[i].properties.noteIndex]);
+			citationIndices.push(i);
+		}
+	}
+	citationIndices.push(index);
+	var citationsPost = [];
+	for(var i=index+1; i<this.citationsByIndex.length; i++) {
+		if(this.citationsByIndex[i] && !this.newIndices[i] && !this.citationsByIndex[i].properties.delete) {
+			citationsPost.push([this.citationsByIndex[i].citationID, this.citationsByIndex[i].properties.noteIndex]);
+			citationIndices.push(i);
+		}
+	}
+	return [citationsPre, citationsPost, citationIndices];
+}
+
 /**
  * Returns a formatted citation
  */
 Zotero.Integration.Session.prototype.formatCitation = function(index, citation) {
 	if(!this.citationText[index]) {
-		var citationIndices = [];
-		var citationsPre = [];
-		for(var i=0; i<index; i++) {
-			if(this.citationsByIndex[i] && !this.newIndices[i] && !this.citationsByIndex[i].properties.delete) {
-				citationsPre.push([this.citationsByIndex[i].citationID, this.citationsByIndex[i].properties.noteIndex]);
-				citationIndices.push(i);
-			}
-		}
-		citationIndices.push(index);
-		var citationsPost = [];
-		for(var i=index+1; i<this.citationsByIndex.length; i++) {
-			if(this.citationsByIndex[i] && !this.newIndices[i] && !this.citationsByIndex[i].properties.delete) {
-				citationsPost.push([this.citationsByIndex[i].citationID, this.citationsByIndex[i].properties.noteIndex]);
-				citationIndices.push(i);
-			}
-		}
+		var citationsPre, citationsPost, citationIndices;
+		[citationsPre, citationsPost, citationIndices] = this._getPrePost(index);
 		//Zotero.debug("style.processCitationCluster("+citation.toSource()+", "+citationsPre.toSource()+", "+citationsPost.toSource());
 		var newCitations = this.style.processCitationCluster(citation, citationsPre, citationsPost);
-		for each(var newCitation in newCitations) {
-			Zotero.debug("Zotero.Integration: Citation "+citationIndices[newCitation[0]]+" needs to be updated");
+		for each(var newCitation in newCitations[1]) {
 			this.citationText[citationIndices[newCitation[0]]] = newCitation[1];
 			this.updateIndices[citationIndices[newCitation[0]]] = true;
 		}
-		// this is a heuristic: if other citations get updated, then we should update the
-		// bibliography. it would be nice if citeproc-js gave us a better hint about this
-		return (newCitations.length > 1);
+		return newCitations.bibchange;
 	}
 }
 
@@ -1395,6 +1401,20 @@ Zotero.Integration.Session.prototype.updateCitations = function() {
 	return deleteCitations;
 }
 
+/**
+ * Updates the list of citations to be serialized to the document
+ */
+Zotero.Integration.Session.prototype.restoreProcessorState = function() {
+	var citations = [];
+	for(var i in this.citationsByIndex.length) {
+		if(this.citationsByIndex[i] && !this.newIndices[i] && !this.citationsByIndex[i].properties.delete) {
+			citations.push(this.citationsByIndex[i]);
+		}
+	}
+	
+	this.style.restoreProcessorState(citations);
+}
+
 /**
  * Loads document data from a JSON object
  */
@@ -1494,21 +1514,14 @@ Zotero.Integration.Session.prototype.getBibliographyData = function() {
  * and position)
  */
 Zotero.Integration.Session.prototype.previewCitation = function(citation) {
-	// remove cached citation text
-	this.citationText = {};
-	this.addCitation(citation.properties.index, citation.properties.noteIndex, citation);
-
-	// add citation items
+	var citationsPre, citationsPost, citationIndices;
+	[citationsPre, citationsPost, citationIndices] = this._getPrePost(citation.properties.index);
 	try {
-		this.formatCitation(citation.properties.index, citation);
+		return this.style.previewCitationCluster(citation, citationsPre, citationsPost, "rtf");
 	} catch(e) {
 		Zotero.debug(e);
-		this.deleteCitation(citation.properties.index);
 		throw e;
 	}
-	this.deleteCitation(citation.properties.index);
-	
-	return this.citationText[citation.properties.index];
 } 
 
 /**
@@ -1544,7 +1557,7 @@ Zotero.Integration.Session.prototype.editCitation = function(index, noteIndex, c
 		return me.previewCitation(io.citation);
 	}
 	// determine whether citation is sortable in current style
-	io.sortable = !this.style.citation.opt["citation-number-sort"] && this.style.citation_sort.tokens.length > 0;
+	io.sortable = this.style.opt.sort_citations;
 	
 	var window = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
 		.getService(Components.interfaces.nsIWindowWatcher)