diff --git a/src/components/chips/js/chipController.js b/src/components/chips/js/chipController.js index c5b594877d..58f6170051 100644 --- a/src/components/chips/js/chipController.js +++ b/src/components/chips/js/chipController.js @@ -4,7 +4,7 @@ angular /** * Controller for the MdChip component. Responsible for handling keyboard - * events and editting the chip if needed. + * events and editing the chip if needed. * * @param $scope * @param $element @@ -42,7 +42,7 @@ function MdChipCtrl ($scope, $element, $mdConstant, $timeout, $mdUtil) { /** * @type {boolean} */ - this.isEditting = false; + this.isEditing = false; /** * @type {MdChipsCtrl} @@ -65,14 +65,14 @@ MdChipCtrl.prototype.init = function(controller) { if (this.enableChipEdit) { this.$element.on('keydown', this.chipKeyDown.bind(this)); - this.$element.on('mousedown', this.chipMouseDown.bind(this)); + this.$element.on('dblclick', this.chipMouseDoubleClick.bind(this)); this.getChipContent().addClass('_md-chip-content-edit-is-enabled'); } }; /** - * @return {Object} + * @return {Object} first element with the md-chip-content class */ MdChipCtrl.prototype.getChipContent = function() { var chipContents = this.$element[0].getElementsByClassName('md-chip-content'); @@ -81,15 +81,15 @@ MdChipCtrl.prototype.getChipContent = function() { /** - * @return {Object} + * @return {Object} first content element of the chips content element */ MdChipCtrl.prototype.getContentElement = function() { - return angular.element(this.getChipContent().children()[0]); + return angular.element(this.getChipContent().contents()[0]); }; /** - * @return {number} + * @return {number} index of this chip */ MdChipCtrl.prototype.getChipIndex = function() { return parseInt(this.$element.attr('index')); @@ -97,12 +97,13 @@ MdChipCtrl.prototype.getChipIndex = function() { /** - * Presents an input element to edit the contents of the chip. + * Update the chip's contents, focus the chip if it's selected, and exit edit mode. + * If the contents were updated to be empty, remove the chip and re-focus the input element. */ MdChipCtrl.prototype.goOutOfEditMode = function() { - if (!this.isEditting) return; + if (!this.isEditing) return; - this.isEditting = false; + this.isEditing = false; this.$element.removeClass('_md-chip-editing'); this.getChipContent()[0].contentEditable = 'false'; var chipIndex = this.getChipIndex(); @@ -127,7 +128,7 @@ MdChipCtrl.prototype.goOutOfEditMode = function() { /** * Given an HTML element. Selects contents of it. - * @param node + * @param {Element} node */ MdChipCtrl.prototype.selectNodeContents = function(node) { var range, selection; @@ -149,7 +150,7 @@ MdChipCtrl.prototype.selectNodeContents = function(node) { * Presents an input element to edit the contents of the chip. */ MdChipCtrl.prototype.goInEditMode = function() { - this.isEditting = true; + this.isEditing = true; this.$element.addClass('_md-chip-editing'); this.getChipContent()[0].contentEditable = 'true'; this.getChipContent().on('blur', function() { @@ -164,15 +165,15 @@ MdChipCtrl.prototype.goInEditMode = function() { * Handles the keydown event on the chip element. If enable-chip-edit attribute is * set to true, space or enter keys can trigger going into edit mode. Enter can also * trigger submitting if the chip is already being edited. - * @param event + * @param {KeyboardEvent} event */ MdChipCtrl.prototype.chipKeyDown = function(event) { - if (!this.isEditting && + if (!this.isEditing && (event.keyCode === this.$mdConstant.KEY_CODE.ENTER || event.keyCode === this.$mdConstant.KEY_CODE.SPACE)) { event.preventDefault(); this.goInEditMode(); - } else if (this.isEditting && + } else if (this.isEditing && event.keyCode === this.$mdConstant.KEY_CODE.ENTER) { event.preventDefault(); this.goOutOfEditMode(); @@ -181,12 +182,10 @@ MdChipCtrl.prototype.chipKeyDown = function(event) { /** - * Handles the double click event + * Enter edit mode if we're not already editing and the enable-chip-edit attribute is enabled. */ -MdChipCtrl.prototype.chipMouseDown = function() { - if(this.getChipIndex() == this.parentController.selectedChip && - this.enableChipEdit && - !this.isEditting) { +MdChipCtrl.prototype.chipMouseDoubleClick = function() { + if (this.enableChipEdit && !this.isEditing) { this.goInEditMode(); } }; diff --git a/src/components/chips/js/chipDirective.js b/src/components/chips/js/chipDirective.js index 83f86da2cd..aa954c366e 100644 --- a/src/components/chips/js/chipDirective.js +++ b/src/components/chips/js/chipDirective.js @@ -8,20 +8,21 @@ angular * @module material.components.chips * * @description - * `` is a component used within `` and is responsible for rendering individual - * chips. + * `` is a component used within ``. It is responsible for rendering an + * individual chip. * * * @usage * - * {{$chip}} + * + * {{$chip}} + * * * */ -// This hint text is hidden within a chip but used by screen readers to +// This hint text is visually hidden within a chip but used by screen readers to // inform the user how they can interact with a chip. - var DELETE_HINT_TEMPLATE = '\ \ {{$mdChipsCtrl.deleteHint}}\ @@ -32,6 +33,8 @@ var DELETE_HINT_TEMPLATE = '\ * * @param $mdTheming * @param $mdUtil + * @param $compile + * @param $timeout * @ngInject */ function MdChip($mdTheming, $mdUtil, $compile, $timeout) { diff --git a/src/components/chips/js/chipsController.js b/src/components/chips/js/chipsController.js index 155ea05fc3..2d8b812514 100644 --- a/src/components/chips/js/chipsController.js +++ b/src/components/chips/js/chipsController.js @@ -142,7 +142,7 @@ function MdChipsCtrl ($scope, $attrs, $mdConstant, $log, $element, $timeout, $md * Array of unique numbers which will be auto-generated any time the items change, and is used to * create unique IDs for the aria-owns attribute. * - * @type {Array} + * @type {Array} */ this.contentIds = []; @@ -255,7 +255,7 @@ MdChipsCtrl.prototype.setupWrapperAria = function() { * Handles the keydown event on the input element: by default appends * the buffer to the chip list, while backspace removes the last chip in the * list if the current buffer is empty. - * @param event + * @param {jQuery.Event|KeyboardEvent} event */ MdChipsCtrl.prototype.inputKeydown = function(event) { var chipBuffer = this.getChipBuffer(); @@ -304,7 +304,7 @@ MdChipsCtrl.prototype.inputKeydown = function(event) { /** * Returns the cursor position of the specified input element. - * @param element HTMLInputElement + * @param {HTMLInputElement} element relevant input element * @returns {Number} Cursor Position of the input. */ MdChipsCtrl.prototype.getCursorPosition = function(element) { @@ -327,10 +327,10 @@ MdChipsCtrl.prototype.getCursorPosition = function(element) { /** * Updates the content of the chip at given index - * @param chipIndex - * @param chipContents + * @param {number} chipIndex + * @param {string} chipContents */ -MdChipsCtrl.prototype.updateChipContents = function(chipIndex, chipContents){ +MdChipsCtrl.prototype.updateChipContents = function(chipIndex, chipContents) { if (chipIndex >= 0 && chipIndex < this.items.length) { this.items[chipIndex] = chipContents; this.updateNgModel(true); @@ -339,8 +339,7 @@ MdChipsCtrl.prototype.updateChipContents = function(chipIndex, chipContents){ /** - * Returns true if a chip is currently being edited. False otherwise. - * @return {boolean} + * @return {boolean} true if a chip is currently being edited. False otherwise. */ MdChipsCtrl.prototype.isEditingChip = function() { return !!this.$element[0].querySelector('._md-chip-editing'); @@ -359,8 +358,8 @@ MdChipsCtrl.prototype.isRemovable = function() { /** * Handles the keydown event on the chip elements: backspace removes the selected chip, arrow - * keys switch which chips is active - * @param event + * keys switch which chip is active. + * @param {KeyboardEvent} event */ MdChipsCtrl.prototype.chipKeydown = function (event) { if (this.getChipBuffer()) return; @@ -378,8 +377,8 @@ MdChipsCtrl.prototype.chipKeydown = function (event) { case this.$mdConstant.KEY_CODE.LEFT_ARROW: event.preventDefault(); // By default, allow selection of -1 which will focus the input; if we're readonly, don't go - // below 0 - if (this.selectedChip < 0 || (this.readonly && this.selectedChip == 0)) { + // below 0. + if (this.selectedChip < 0 || (this.readonly && this.selectedChip === 0)) { this.selectedChip = this.items.length; } if (this.items.length) this.selectAndFocusChipSafe(this.selectedChip - 1); @@ -401,17 +400,18 @@ MdChipsCtrl.prototype.chipKeydown = function (event) { * Get the input's placeholder - uses `placeholder` when list is empty and `secondary-placeholder` * when the list is non-empty. If `secondary-placeholder` is not provided, `placeholder` is used * always. + * @returns {string} */ MdChipsCtrl.prototype.getPlaceholder = function() { // Allow `secondary-placeholder` to be blank. var useSecondary = (this.items && this.items.length && - (this.secondaryPlaceholder == '' || this.secondaryPlaceholder)); + (this.secondaryPlaceholder === '' || this.secondaryPlaceholder)); return useSecondary ? this.secondaryPlaceholder : this.placeholder; }; /** * Removes chip at {@code index} and selects the adjacent chip. - * @param {number} index + * @param {number} index adjacent chip to select * @param {Event=} event */ MdChipsCtrl.prototype.removeAndSelectAdjacentChip = function(index, event) { @@ -449,11 +449,13 @@ MdChipsCtrl.prototype.resetSelectedChip = function() { * The number returned is the index to select AFTER the target has been * removed. * If the current chip is not selected, then -1 is returned to select none. + * @param {number} index + * @returns {number} */ MdChipsCtrl.prototype.getAdjacentChipIndex = function(index) { var len = this.items.length - 1; - return (len == 0) ? -1 : - (index == len) ? index -1 : index; + return (len === 0) ? -1 : + (index === len) ? index -1 : index; }; /** @@ -529,7 +531,7 @@ MdChipsCtrl.prototype.useOnRemoveExpression = function() { this.useOnRemove = true; }; -/* +/** * Sets whether to use the md-on-select expression. This expression is * bound to scope and controller in {@code MdChipsDirective} as * {@code onSelect}. Due to the nature of directive scope bindings, the @@ -546,7 +548,7 @@ MdChipsCtrl.prototype.useOnSelectExpression = function() { * model of an {@code md-autocomplete}, or, through some magic, the model * bound to any input or text area element found within a * {@code md-input-container} element. - * @return {string} + * @return {string} the input buffer */ MdChipsCtrl.prototype.getChipBuffer = function() { var chipBuffer = !this.userInputElement ? this.chipBuffer : @@ -574,6 +576,9 @@ MdChipsCtrl.prototype.resetChipBuffer = function() { } }; +/** + * @returns {boolean} true if the max chips limit has been reached, false otherwise. + */ MdChipsCtrl.prototype.hasMaxChipsReached = function() { if (angular.isString(this.maxChips)) this.maxChips = parseInt(this.maxChips, 10) || 0; @@ -625,6 +630,10 @@ MdChipsCtrl.prototype.removeChip = function(index, event) { } }; +/** + * @param {number} index location of chip to remove + * @param {Event=} $event + */ MdChipsCtrl.prototype.removeChipAndFocusInput = function (index, $event) { this.removeChip(index, $event); @@ -641,7 +650,7 @@ MdChipsCtrl.prototype.removeChipAndFocusInput = function (index, $event) { }; /** * Selects the chip at `index`, - * @param index + * @param {number} index location of chip to select and focus */ MdChipsCtrl.prototype.selectAndFocusChipSafe = function(index) { // If we have no chips, or are asked to select a chip before the first, just focus the input @@ -667,6 +676,9 @@ MdChipsCtrl.prototype.selectAndFocusChipSafe = function(index) { this.focusChip(index); }; +/** + * Focus last chip, then focus the input. This is needed for screen reader support. + */ MdChipsCtrl.prototype.focusLastChipThenInput = function() { var ctrl = this; @@ -679,6 +691,9 @@ MdChipsCtrl.prototype.focusLastChipThenInput = function() { }, ctrl.chipAppendDelay); }; +/** + * Focus the input element. + */ MdChipsCtrl.prototype.focusInput = function() { this.selectChip(-1); this.onFocus(); @@ -686,7 +701,7 @@ MdChipsCtrl.prototype.focusInput = function() { /** * Marks the chip at the given index as selected. - * @param index + * @param {number} index location of chip to select */ MdChipsCtrl.prototype.selectChip = function(index) { if (index >= -1 && index <= this.items.length) { @@ -702,18 +717,20 @@ MdChipsCtrl.prototype.selectChip = function(index) { }; /** - * Selects the chip at `index` and gives it focus. - * @param index + * Selects the chip at {@code index} and gives it focus. + * @param {number} index location of chip to select and focus + * @deprecated use MdChipsCtrl.selectAndFocusChipSafe. Will be removed in 1.2. */ MdChipsCtrl.prototype.selectAndFocusChip = function(index) { this.selectChip(index); - if (index != -1) { + if (index !== -1) { this.focusChip(index); } }; /** - * Call `focus()` on the chip at `index` + * Call {@code focus()} on the chip at {@code index} + * @param {number} index location of chip to focus */ MdChipsCtrl.prototype.focusChip = function(index) { var chipContent = this.$element[0].querySelector('md-chip[index="' + index + '"] .md-chip-content'); @@ -725,8 +742,8 @@ MdChipsCtrl.prototype.focusChip = function(index) { /** * Configures the required interactions with the ngModel Controller. - * Specifically, set {@code this.items} to the {@code NgModelCtrl#$viewValue}. - * @param ngModelCtrl + * Specifically, set {@code this.items} to the {@code NgModelController#$viewValue}. + * @param {NgModelController} ngModelCtrl */ MdChipsCtrl.prototype.configureNgModel = function(ngModelCtrl) { this.ngModelCtrl = ngModelCtrl; @@ -771,7 +788,7 @@ MdChipsCtrl.prototype.onInputBlur = function () { /** * Configure event bindings on input element. - * @param inputElement + * @param {angular.element} inputElement */ MdChipsCtrl.prototype.configureInput = function configureInput(inputElement) { // Find the NgModelCtrl for the input element @@ -808,7 +825,7 @@ MdChipsCtrl.prototype.configureInput = function configureInput(inputElement) { /** * Configure event bindings on a user-provided input element. - * @param inputElement + * @param {angular.element} inputElement */ MdChipsCtrl.prototype.configureUserInput = function(inputElement) { this.userInputElement = inputElement; @@ -836,6 +853,9 @@ MdChipsCtrl.prototype.configureUserInput = function(inputElement) { .on('blur', function(event) { scopeApplyFn(event, ctrl.onInputBlur) }); }; +/** + * @param {MdAutocompleteCtrl} ctrl controller from the autocomplete component + */ MdChipsCtrl.prototype.configureAutocomplete = function(ctrl) { if (ctrl) { this.autocompleteCtrl = ctrl; @@ -857,8 +877,7 @@ MdChipsCtrl.prototype.configureAutocomplete = function(ctrl) { }; /** - * Whether the current chip buffer should be added on input blur or not. - * @returns {boolean} + * @returns {boolean} Whether the current chip buffer should be added on input blur or not. */ MdChipsCtrl.prototype.shouldAddOnBlur = function() { @@ -879,10 +898,17 @@ MdChipsCtrl.prototype.shouldAddOnBlur = function() { return this.addOnBlur && !this.requireMatch && chipBuffer && isModelValid && !isAutocompleteShowing; }; +/** + * @returns {boolean} true if the input or a chip is focused. False otherwise. + */ MdChipsCtrl.prototype.hasFocus = function () { return this.inputHasFocus || this.selectedChip >= 0; }; +/** + * @param {number} index location of content id + * @returns {number} unique id for the aria-owns attribute + */ MdChipsCtrl.prototype.contentIdFor = function(index) { return this.contentIds[index]; }; diff --git a/src/components/chips/js/chipsDirective.js b/src/components/chips/js/chipsDirective.js index 742df538ea..98725312c5 100644 --- a/src/components/chips/js/chipsDirective.js +++ b/src/components/chips/js/chipsDirective.js @@ -112,15 +112,17 @@ * marked as readonly.

* When `md-removable` is not defined, the `md-remove` behavior will be overwritten and * disabled. - * @param {string=} md-enable-chip-edit Set this to "true" to enable editing of chip contents. - * The user can go into edit mode with pressing "space", "enter", or double clicking on the - * chip. Chip edit is only supported for chips with basic template. + * @param {boolean=} md-enable-chip-edit Set this to `"true"` to enable editing of chip contents. + * The user can go into edit mode by pressing the `space` or `enter` keys, or by double + * clicking on the chip. Chip editing is only supported for chips using the basic template. + * **Note:** This attribute is only evaluated once; it is not watched. * @param {boolean=} ng-required Whether ng-model is allowed to be empty or not. * @param {number=} md-max-chips The maximum number of chips allowed to add through user input. *

The validation property `md-max-chips` can be used when the max chips * amount is reached. - * @param {boolean=} md-add-on-blur When set to true, remaining text inside of the input will - * be converted into a new chip on blur. + * @param {boolean=} md-add-on-blur When set to `"true"`, the remaining text inside of the input + * will be converted into a new chip on blur. + * **Note:** This attribute is only evaluated once; it is not watched. * @param {expression} md-transform-chip An expression of form `myFunction($chip)` that when * called expects one of the following return values: * - an object representing the `$chip` input string