Update to MediaWiki 1.25.1

1 files changed, 100 insertions, 49 deletions

diff --git a/resources/src/jquery/jquery.suggestions.js b/resources/src/jquery/jquery.suggestions.js
index 3369cde2..813c37ce 100644
--- a/resources/src/jquery/jquery.suggestions.js
+++ b/resources/src/jquery/jquery.suggestions.js
@@ -1,58 +1,102 @@
 /**
  * This plugin provides a generic way to add suggestions to a text box.
  *
- * Usage:
- *
  * Set options:
+ *
  *		$( '#textbox' ).suggestions( { option1: value1, option2: value2 } );
  *		$( '#textbox' ).suggestions( option, value );
+ *
  * Get option:
+ *
  *		value = $( '#textbox' ).suggestions( option );
+ *
  * Initialize:
+ *
  *		$( '#textbox' ).suggestions();
  *
- * Options:
+ * Uses jQuery.suggestions singleteon internally.
  *
- * fetch(query): Callback that should fetch suggestions and set the suggestions property.
- *      Executed in the context of the textbox
- *		Type: Function
- * cancel: Callback function to call when any pending asynchronous suggestions fetches
- *      should be canceled. Executed in the context of the textbox
- *		Type: Function
- * special: Set of callbacks for rendering and selecting
- *		Type: Object of Functions 'render' and 'select'
- * result: Set of callbacks for rendering and selecting
- *		Type: Object of Functions 'render' and 'select'
- * $region: jQuery selection of element to place the suggestions below and match width of
- *		Type: jQuery Object, Default: $( this )
- * suggestions: Suggestions to display
- *		Type: Array of strings
- * maxRows: Maximum number of suggestions to display at one time
- *		Type: Number, Range: 1 - 100, Default: 7
- * delay: Number of ms to wait for the user to stop typing
- *		Type: Number, Range: 0 - 1200, Default: 120
- * cache: Whether to cache results from a fetch
- *		Type: Boolean, Default: false
- * cacheMaxAge: Number of ms to cache results from a fetch
- *		Type: Number, Range: 1 - Infinity, Default: 60000 (1 minute)
- * submitOnClick: Whether to submit the form containing the textbox when a suggestion is clicked
- *		Type: Boolean, Default: false
- * maxExpandFactor: Maximum suggestions box width relative to the textbox width. If set
- *      to e.g. 2, the suggestions box will never be grown beyond 2 times the width of the textbox.
- *		Type: Number, Range: 1 - infinity, Default: 3
- * expandFrom: Which direction to offset the suggestion box from.
- *      Values 'start' and 'end' translate to left and right respectively depending on the
- *      directionality of the current document, according to $( 'html' ).css( 'direction' ).
- *      Type: String, default: 'auto', options: 'left', 'right', 'start', 'end', 'auto'.
- * positionFromLeft: Sets expandFrom=left, for backwards compatibility
- *		Type: Boolean, Default: true
- * highlightInput: Whether to hightlight matched portions of the input or not
- *		Type: Boolean, Default: false
+ * @class jQuery.plugin.suggestions
+ */
+/**
+ * @method suggestions
+ * @return {jQuery}
+ * @chainable
+ *
+ * @param {Object} options
+ *
+ * @param {Function} [options.fetch] Callback that should fetch suggestions and set the suggestions
+ *  property. Called in context of the text box.
+ * @param {string} options.fetch.query
+ * @param {Function} options.fetch.response Callback to receive the suggestions with
+ * @param {Array} options.fetch.response.suggestions
+ * @param {number} options.fetch.maxRows
+ *
+ * @param {Function} [options.cancel] Callback function to call when any pending asynchronous
+ *  suggestions fetches. Called in context of the text box.
+ *
+ * @param {Object} [options.special] Set of callbacks for rendering and selecting.
+ *
+ * @param {Function} options.special.render Called in context of the suggestions-special element.
+ * @param {string} options.special.render.query
+ * @param {Object} options.special.render.context
+ *
+ * @param {Function} options.special.select Called in context of the suggestions-result-current element.
+ * @param {jQuery} options.special.select.$textbox
+ *
+ * @param {Object} [options.result] Set of callbacks for rendering and selecting
+ *
+ * @param {Function} options.result.render Called in context of the suggestions-result element.
+ * @param {string} options.result.render.suggestion
+ * @param {Object} options.result.render.context
+ *
+ * @param {Function} options.result.select Called in context of the suggestions-result-current element.
+ * @param {jQuery} options.result.select.$textbox
+ *
+ * @param {jQuery} [options.$region=this] The element to place the suggestions below and match width of.
+ *
+ * @param {string[]} [options.suggestions] Array of suggestions to display.
+ *
+ * @param {number} [options.maxRows=10] Maximum number of suggestions to display at one time.
+ *  Must be between 1 and 100.
+ *
+ * @param {number} [options.delay=120] Number of milliseconds to wait for the user to stop typing.
+ *  Must be between 0 and 1200.
+ *
+ * @param {boolean} [options.cache=false] Whether to cache results from a fetch.
+ *
+ * @param {number} [options.cacheMaxAge=60000] Number of milliseconds to cache results from a fetch.
+ *  Must be higher than 1. Defaults to 1 minute.
+ *
+ * @param {boolean} [options.submitOnClick=false] Whether to submit the form containing the textbox
+ *  when a suggestion is clicked.
+ *
+ * @param {number} [options.maxExpandFactor=3] Maximum suggestions box width relative to the textbox
+ *  width. If set to e.g. 2, the suggestions box will never be grown beyond 2 times the width of
+ *  the textbox. Must be higher than 1.
+ *
+ * @param {string} [options.expandFrom=auto] Which direction to offset the suggestion box from.
+ *  Values 'start' and 'end' translate to left and right respectively depending on the directionality
+ *   of the current document, according to `$( 'html' ).css( 'direction' )`.
+ *   Valid values: "left", "right", "start", "end", and "auto".
+ *
+ * @param {boolean} [options.positionFromLeft] Sets `expandFrom=left`, for backwards
+ *  compatibility.
+ *
+ * @param {boolean} [options.highlightInput=false] Whether to hightlight matched portions of the
+ *  input or not.
  */
 ( function ( $ ) {
 
 var hasOwn = Object.hasOwnProperty;
 
+/**
+ * Used by jQuery.plugin.suggestions.
+ *
+ * @class jQuery.suggestions
+ * @singleton
+ * @private
+ */
 $.suggestions = {
 	/**
 	 * Cancel any delayed maybeFetch() call and callback the context so
@@ -92,7 +136,7 @@ $.suggestions = {
 	 * call to this function still pending will be canceled. If the value in the
 	 * textbox is empty or hasn't changed since the last time suggestions were fetched,
 	 * this function does nothing.
-	 * @param {Boolean} delayed Whether or not to delay this by the currently configured amount of time
+	 * @param {boolean} delayed Whether or not to delay this by the currently configured amount of time
 	 */
 	update: function ( context, delayed ) {
 		function maybeFetch() {
@@ -125,6 +169,7 @@ $.suggestions = {
 						context.data.$textbox,
 						val,
 						function ( suggestions ) {
+							suggestions = suggestions.slice( 0, context.config.maxRows );
 							context.data.$textbox.suggestions( 'suggestions', suggestions );
 							if ( context.config.cache ) {
 								cache[ val ] = {
@@ -132,7 +177,8 @@ $.suggestions = {
 									timestamp: +new Date()
 								};
 							}
-						}
+						},
+						context.config.maxRows
 					);
 				}
 			}
@@ -167,8 +213,8 @@ $.suggestions = {
 
 	/**
 	 * Sets the value of a property, and updates the widget accordingly
-	 * @param property String Name of property
-	 * @param value Mixed Value to set property with
+	 * @param {string} property Name of property
+	 * @param {Mixed} value Value to set property with
 	 */
 	configure: function ( context, property, value ) {
 		var newCSS,
@@ -352,8 +398,8 @@ $.suggestions = {
 
 	/**
 	 * Highlight a result in the results table
-	 * @param result <tr> to highlight: jQuery object, or 'prev' or 'next'
-	 * @param updateTextbox If true, put the suggestion in the textbox
+	 * @param {jQuery|string} result `<tr>` to highlight, or 'prev' or 'next'
+	 * @param {boolean} updateTextbox If true, put the suggestion in the textbox
 	 */
 	highlight: function ( context, result, updateTextbox ) {
 		var selected = context.data.$container.find( '.suggestions-result-current' );
@@ -421,7 +467,7 @@ $.suggestions = {
 
 	/**
 	 * Respond to keypress event
-	 * @param key Integer Code of key pressed
+	 * @param {number} key Code of key pressed
 	 */
 	keypress: function ( e, context, key ) {
 		var selected,
@@ -474,8 +520,6 @@ $.suggestions = {
 						}
 					}
 				} else {
-					$.suggestions.highlight( context, selected, true );
-
 					if ( typeof context.config.result.select === 'function' ) {
 						// Allow the callback to decide whether to prevent default or not
 						if ( context.config.result.select.call( selected, context.data.$textbox ) === true ) {
@@ -494,6 +538,8 @@ $.suggestions = {
 		}
 	}
 };
+
+// See file header for method documentation
 $.fn.suggestions = function () {
 
 	// Multi-context fields
@@ -503,7 +549,7 @@ $.fn.suggestions = function () {
 	$( this ).each( function () {
 		var context, key;
 
-		/* Construction / Loading */
+		/* Construction and Loading */
 
 		context = $( this ).data( 'suggestions-context' );
 		if ( context === undefined || context === null ) {
@@ -515,7 +561,7 @@ $.fn.suggestions = function () {
 					result: {},
 					$region: $( this ),
 					suggestions: [],
-					maxRows: 7,
+					maxRows: 10,
 					delay: 120,
 					cache: false,
 					cacheMaxAge: 60000,
@@ -681,4 +727,9 @@ $.fn.suggestions = function () {
 	return returnValue !== undefined ? returnValue : $( this );
 };
 
+/**
+ * @class jQuery
+ * @mixins jQuery.plugin.suggestions
+ */
+
 }( jQuery ) );