diff --git a/externs/polymer-externs.js b/externs/polymer-externs.js index 0a4aa90272..8c426f3703 100644 --- a/externs/polymer-externs.js +++ b/externs/polymer-externs.js @@ -48,6 +48,7 @@ PolymerInit.prototype.hostAttributes; /** @type {(!Object | undefined)} */ PolymerInit.prototype.listeners; +/** @record */ let PolymerElementConstructor = function () {}; /** @type {(string | undefined)} */ PolymerElementConstructor.is; @@ -78,6 +79,26 @@ function Polymer(init){} */ Polymer.sanitizeDOMValue; +/** + * @type {boolean} + */ +Polymer.passiveTouchGestures; + +/** + * @type {boolean} + */ +Polymer.strictTemplatePolicy; + +/** + * @type {boolean} + */ +Polymer.allowTemplateFromDomModule; + +/** + * @type {string} + */ +Polymer.rootPath; + /** * @param {string} string * @param {Object} obj @@ -174,7 +195,7 @@ var PolymerDeepPropertyChange; * @constructor * @template T */ -let DomRepeatEvent = function() {}; +var DomRepeatEvent = function() {}; /** * @type {{ diff --git a/externs/webcomponents-externs.js b/externs/webcomponents-externs.js index df0f46b8f0..99708b9e16 100644 --- a/externs/webcomponents-externs.js +++ b/externs/webcomponents-externs.js @@ -12,23 +12,37 @@ */ /* eslint-disable */ -let ShadyDOM = { +var HTMLImports = { + /** + * @param {function()} callback + */ + whenReady(callback) {}, + /** + * @param {Element} element + * @returns {Document} document + */ + importForElement(element) {} +}; + +window.HTMLImports = HTMLImports; + +var ShadyDOM = { inUse: false, - flush(){}, + flush() {}, /** * @param {!Node} target * @param {function(Array, MutationObserver)} callback * @return {MutationObserver} */ - observeChildren(target, callback){}, + observeChildren(target, callback) {}, /** * @param {MutationObserver} observer */ - unobserveChildren(observer){}, + unobserveChildren(observer) {}, /** * @param {Node} node */ - patch(node){} + patch(node) {} }; window.ShadyDOM = ShadyDOM; diff --git a/gen-tsd.json b/gen-tsd.json index c974686179..abb67b6cab 100644 --- a/gen-tsd.json +++ b/gen-tsd.json @@ -7,6 +7,9 @@ "util/**", "index.html" ], + "excludeIdentifiers": [ + "templatizedBase" + ], "removeReferences": [ "../shadycss/apply-shim.d.ts", "../shadycss/custom-style-interface.d.ts" @@ -32,7 +35,8 @@ "Binding", "AsyncInterface", "GestureRecognizer", - "IdleDeadline" + "IdleDeadline", + "PolymerElementConstructor" ], "./lib/utils/debounce.js": [ "Debouncer" diff --git a/interfaces.d.ts b/interfaces.d.ts index 61e0a2d37c..5c04d71619 100644 --- a/interfaces.d.ts +++ b/interfaces.d.ts @@ -191,3 +191,12 @@ export interface IdleDeadline { didTimeout: boolean; timeRemaining(): number; } + +export interface PolymerElementConstructor { + new (): HTMLElement; + is?: string; + extends?: string; + properties?: PolymerElementProperties; + observers?: string[]; + template?: string|HTMLTemplateElement|null; +} diff --git a/lib/elements/array-selector.js b/lib/elements/array-selector.js index 51a553c670..c4a9816749 100644 --- a/lib/elements/array-selector.js +++ b/lib/elements/array-selector.js @@ -37,7 +37,6 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * @constructor - * @extends {superClass} * @implements {Polymer_ElementMixin} * @private */ @@ -52,7 +51,6 @@ let ArraySelectorMixin = dedupingMixin(superClass => { class ArraySelectorMixin extends elementBase { static get properties() { - return { /** @@ -76,31 +74,22 @@ let ArraySelectorMixin = dedupingMixin(superClass => { * When `multi` is true, this is an array that contains any selected. * When `multi` is false, this is the currently selected item, or `null` * if no item is selected. - * @type {?(Object|Array)} + * @type {?Object|?Array} */ - selected: { - type: Object, - notify: true - }, + selected: {type: Object, notify: true}, /** * When `multi` is false, this is the currently selected item, or `null` * if no item is selected. * @type {?Object} */ - selectedItem: { - type: Object, - notify: true - }, + selectedItem: {type: Object, notify: true}, /** * When `true`, calling `select` on an item that is already selected * will deselect the item. */ - toggle: { - type: Boolean, - value: false - } + toggle: {type: Boolean, value: false} }; } @@ -208,6 +197,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * Clears the selection state. + * @override * @return {void} */ clearSelection() { @@ -226,6 +216,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * Returns whether the item is currently selected. * + * @override * @param {*} item Item from `items` array to test * @return {boolean} Whether the item is selected */ @@ -236,6 +227,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * Returns whether the item is currently selected. * + * @override * @param {number} idx Index from `items` array to test * @return {boolean} Whether the item is selected */ @@ -265,6 +257,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * Deselects the given item if it is already selected. * + * @override * @param {*} item Item from `items` array to deselect * @return {void} */ @@ -288,6 +281,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { /** * Deselects the given index if it is already selected. * + * @override * @param {number} idx Index from `items` array to deselect * @return {void} */ @@ -299,6 +293,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { * Selects the given item. When `toggle` is true, this will automatically * deselect the item if already selected. * + * @override * @param {*} item Item from `items` array to select * @return {void} */ @@ -310,6 +305,7 @@ let ArraySelectorMixin = dedupingMixin(superClass => { * Selects the given index. When `toggle` is true, this will automatically * deselect the item if already selected. * + * @override * @param {number} idx Index from `items` array to select * @return {void} */ diff --git a/lib/legacy/legacy-data-mixin.js b/lib/legacy/legacy-data-mixin.js index e21e098917..0788e4a3c6 100644 --- a/lib/legacy/legacy-data-mixin.js +++ b/lib/legacy/legacy-data-mixin.js @@ -28,10 +28,10 @@ const UndefinedArgumentError = class extends Error { /** * Wraps effect functions to catch `UndefinedArgumentError`s and warn. - * + * * @param {Object=} effect Effect metadata object * @param {Object=} fnName Name of user function, if known - * @return {?Object} Effect metadata object + * @return {?Object|undefined} Effect metadata object */ function wrapEffect(effect, fnName) { if (effect && effect.fn) { @@ -41,7 +41,7 @@ function wrapEffect(effect, fnName) { fn.apply(this, arguments); } catch (e) { if (e instanceof UndefinedArgumentError) { - console.warn(`Argument '${e.arg}'${fnName ?` for method '${fnName}'` : ''} was undefined. Ensure it has an undefined check.`); + console.warn(`Argument '${e.arg}'${fnName ?` for method '${fnName}'` : ''} was undefined. Ensure it has a default value, or else ensure the method handles the argument being undefined.`); } else { throw e; } @@ -55,11 +55,11 @@ function wrapEffect(effect, fnName) { * Mixin to selectively add back Polymer 1.x's `undefined` rules * governing when observers & computing functions run based * on all arguments being defined (reference https://www.polymer-project.org/1.0/docs/devguide/observers#multi-property-observers). - * + * * When loaded, all legacy elements (defined with `Polymer({...})`) * will have the mixin applied. The mixin only restores legacy data handling * if `_legacyUndefinedCheck: true` is set on the element's prototype. - * + * * This mixin is intended for use to help migration from Polymer 1.x to * 2.x+ by allowing legacy code to work while identifying observers and * computing functions that need undefined checks to work without @@ -73,15 +73,14 @@ function wrapEffect(effect, fnName) { export const LegacyDataMixin = dedupingMixin(superClass => { /** - * @constructor - * @extends {superClass} * @unrestricted - * @private */ + * @private + */ class LegacyDataMixin extends superClass { /** * Overrides `Polymer.PropertyEffects` to add `undefined` argument * checking to match Polymer 1.x style rules - * + * * @param {!Array} args Array of argument metadata * @param {string} path Property/path name that triggered the method effect * @param {Object} props Bag of current property changes @@ -99,7 +98,7 @@ export const LegacyDataMixin = dedupingMixin(superClass => { // Break out of effect's control flow; will be caught in // wrapped property effect function below const name = args[i].name; - throw new UndefinedArgumentError(`Argument '${name}' is undefined. Ensure it has an undefined check.`, name); + throw new UndefinedArgumentError(`Argument '${name}' is undefined.`, name); } } } @@ -109,7 +108,7 @@ export const LegacyDataMixin = dedupingMixin(superClass => { /** * Overrides `Polyer.PropertyEffects` to wrap effect functions to * catch `UndefinedArgumentError`s and warn. - * + * * @param {string} property Property that should trigger the effect * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object @@ -144,9 +143,9 @@ export const LegacyDataMixin = dedupingMixin(superClass => { // LegacyDataMixin is applied to base class _before_ metaprogramming, to // ensure override of _addPropertyEffect et.al. are used by metaprogramming // performed in _finalizeClass -Polymer.Class = (info, mixin) => Class(info, - superClass => mixin ? - mixin(LegacyDataMixin(superClass)) : +Polymer.Class = (info, mixin) => Class(info, + superClass => mixin ? + mixin(LegacyDataMixin(superClass)) : LegacyDataMixin(superClass) ); diff --git a/lib/legacy/legacy-element-mixin.js b/lib/legacy/legacy-element-mixin.js index b06f65fc55..c406f0a6d2 100644 --- a/lib/legacy/legacy-element-mixin.js +++ b/lib/legacy/legacy-element-mixin.js @@ -38,13 +38,12 @@ let styleInterface = window.ShadyCSS; * @summary Element class mixin that provides Polymer's "legacy" API */ export const LegacyElementMixin = dedupingMixin((base) => { - /** * @constructor - * @extends {base} * @implements {Polymer_ElementMixin} * @implements {Polymer_GestureEventListeners} * @implements {Polymer_DirMixin} + * @extends {HTMLElement} * @private */ const legacyElementBase = DirMixin(GestureEventListeners(ElementMixin(base))); @@ -73,9 +72,9 @@ export const LegacyElementMixin = dedupingMixin((base) => { super(); /** @type {boolean} */ this.isAttached; - /** @type {WeakMap>} */ + /** @type {?WeakMap>} */ this.__boundListeners; - /** @type {Object} */ + /** @type {?Object} */ this._debouncers; } @@ -94,6 +93,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { /** * Legacy callback called during the `constructor`, for overriding * by the user. + * @override * @return {void} */ created() {} @@ -113,6 +113,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { /** * Legacy callback called during `connectedCallback`, for overriding * by the user. + * @override * @return {void} */ attached() {} @@ -132,6 +133,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { /** * Legacy callback called during `disconnectedCallback`, for overriding * by the user. + * @override * @return {void} */ detached() {} @@ -160,6 +162,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {?string} old Old value of attribute. * @param {?string} value Current value of attribute. * @return {void} + * @override */ attributeChanged(name, old, value) {} // eslint-disable-line no-unused-vars @@ -196,6 +199,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * only once for the class. * @protected * @return {void} + * @override */ _registered() {} @@ -221,6 +225,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * setting aria roles and focusability. * @protected * @return {void} + * @override */ _ensureAttributes() {} @@ -234,6 +239,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * block render. * @protected * @return {void} + * @override */ _applyListeners() {} @@ -248,6 +254,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * * @param {*} value Value to deserialize * @return {string | undefined} Serialized value + * @override */ serialize(value) { return this._serializeValue(value); @@ -265,6 +272,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string} value String to deserialize * @param {*} type Type to deserialize the string to * @return {*} Returns the deserialized value in the `type` given. + * @override */ deserialize(value, type) { return this._deserializeValue(value, type); @@ -280,6 +288,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string=} attribute Attribute name to reflect. * @param {*=} value Property value to reflect. * @return {void} + * @override */ reflectPropertyToAttribute(property, attribute, value) { this._propertyToAttribute(property, attribute, value); @@ -295,6 +304,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string} attribute Attribute name to serialize to. * @param {Element} node Element to set attribute to. * @return {void} + * @override */ serializeValueToAttribute(value, attribute, node) { this._valueToNodeAttribute(/** @type {Element} */ (node || this), value, attribute); @@ -307,6 +317,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {Object} prototype Target object to copy properties to. * @param {Object} api Source object to copy properties from. * @return {Object} prototype object that was passed as first argument. + * @override */ extend(prototype, api) { if (!(prototype && api)) { @@ -332,6 +343,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {!Object} target Target object to copy properties to. * @param {!Object} source Source object to copy properties from. * @return {!Object} Target object that was passed as first argument. + * @override */ mixin(target, source) { for (let i in source) { @@ -350,6 +362,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * `object`. * @return {Object} Returns the given `object` with its prototype set * to the given `prototype` object. + * @override */ chainObject(object, prototype) { if (object && prototype && object !== prototype) { @@ -367,6 +380,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {HTMLTemplateElement} template HTML template element to instance. * @return {!DocumentFragment} Document fragment containing the imported * template content. + * @override * @suppress {missingProperties} go/missingfnprops */ instanceTemplate(template) { @@ -386,12 +400,14 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string} type Name of event type. * @param {*=} detail Detail value containing event-specific * payload. - * @param {{ bubbles: (boolean|undefined), cancelable: (boolean|undefined), composed: (boolean|undefined) }=} + * @param {{ bubbles: (boolean|undefined), cancelable: (boolean|undefined), + * composed: (boolean|undefined) }=} * options Object specifying options. These may include: * `bubbles` (boolean, defaults to `true`), * `cancelable` (boolean, defaults to false), and * `node` on which to fire the event (HTMLElement, defaults to `this`). * @return {!Event} The new event that was fired. + * @override */ fire(type, detail, options) { options = options || {}; @@ -415,6 +431,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string} eventName Name of event to listen for. * @param {string} methodName Name of handler method on `this` to call. * @return {void} + * @override */ listen(node, eventName, methodName) { node = /** @type {!EventTarget} */ (node || this); @@ -428,7 +445,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { let key = eventName + methodName; if (!bl[key]) { bl[key] = this._addMethodEventListenerToNode( - node, eventName, methodName, this); + /** @type {!Node} */ (node), eventName, methodName, this); } } @@ -441,15 +458,18 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {string} methodName Name of handler method on `this` to not call anymore. * @return {void} + * @override */ unlisten(node, eventName, methodName) { node = /** @type {!EventTarget} */ (node || this); - let bl = this.__boundListeners && this.__boundListeners.get(node); + let bl = this.__boundListeners && + this.__boundListeners.get(/** @type {!Element} */ (node)); let key = eventName + methodName; let handler = bl && bl[key]; if (handler) { - this._removeEventListenerFromNode(node, eventName, handler); - bl[key] = null; + this._removeEventListenerFromNode( + /** @type {!Node} */ (node), eventName, handler); + bl[key] = /** @type {?} */ (null); } } @@ -467,9 +487,12 @@ export const LegacyElementMixin = dedupingMixin((base) => { * @param {Element=} node Element to apply scroll direction setting. * Defaults to `this`. * @return {void} + * @override */ setScrollDirection(direction, node) { - setTouchAction(/** @type {Element} */ (node || this), DIRECTION_MAP[direction] || 'auto'); + setTouchAction( + /** @type {!Element} */ (node || this), + DIRECTION_MAP[direction] || 'auto'); } /* **** End Events **** */ @@ -480,6 +503,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * * @param {string} slctr Selector to run on this local DOM scope * @return {Element} Element found by the selector, or null if not found. + * @override */ $$(slctr) { return this.root.querySelector(slctr); @@ -501,6 +525,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * This should not be necessary as of Polymer 2.0.2 and is provided only * for backwards compatibility. * @return {void} + * @override */ distributeContent() { if (window.ShadyDOM && this.shadowRoot) { @@ -514,11 +539,13 @@ export const LegacyElementMixin = dedupingMixin((base) => { * any `` elements are replaced with the list of nodes distributed * to the ``, the result of its `getDistributedNodes` method. * @return {!Array} List of effective child nodes. - * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement + * @suppress {invalidCasts} LegacyElementMixin must be applied to an + * HTMLElement + * @override */ getEffectiveChildNodes() { const thisEl = /** @type {Element} */ (this); - const domApi = /** @type {DomApi} */(dom(thisEl)); + const domApi = /** @type {PolymerDomApi} */ (dom(thisEl)); return domApi.getEffectiveChildNodes(); } @@ -528,11 +555,13 @@ export const LegacyElementMixin = dedupingMixin((base) => { * children that are insertion points. * @param {string} selector Selector to run. * @return {!Array} List of distributed elements that match selector. - * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement + * @suppress {invalidCasts} LegacyElementMixin must be applied to an + * HTMLElement + * @override */ queryDistributedElements(selector) { const thisEl = /** @type {Element} */ (this); - const domApi = /** @type {DomApi} */(dom(thisEl)); + const domApi = /** @type {PolymerDomApi} */ (dom(thisEl)); return domApi.queryDistributedElements(selector); } @@ -543,6 +572,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * distributed to the ``. * * @return {!Array} List of effective children. + * @override */ getEffectiveChildren() { let list = this.getEffectiveChildNodes(); @@ -557,6 +587,7 @@ export const LegacyElementMixin = dedupingMixin((base) => { * returned by { /** * @constructor - * @extends {superClass} * @implements {Polymer_PropertyAccessors} * @implements {Polymer_TemplateStamp} * @unrestricted @@ -1118,7 +1123,7 @@ export const PropertyEffects = dedupingMixin(superClass => { this.__dataClientsInitialized; /** @type {!Object} */ this.__data; - /** @type {!Object} */ + /** @type {!Object|null} */ this.__dataPending; /** @type {!Object} */ this.__dataOld; @@ -1143,6 +1148,7 @@ export const PropertyEffects = dedupingMixin(superClass => { } /** + * @override * @return {void} */ _initializeProperties() { @@ -1166,7 +1172,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * the prototype on the instance. * * @override - * @param {Object} props Properties to initialize on the prototype + * @param {!Object} props Properties to initialize on the prototype * @return {void} */ _initializeProtoProperties(props) { @@ -1201,6 +1207,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Property that should trigger the effect * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object @@ -1220,6 +1227,7 @@ export const PropertyEffects = dedupingMixin(superClass => { /** * Removes the given property effect. * + * @override * @param {string} property Property the effect was associated with * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object to remove @@ -1237,9 +1245,11 @@ export const PropertyEffects = dedupingMixin(superClass => { * Returns whether the current prototype/instance has a property effect * of a certain type. * + * @override * @param {string} property Property name * @param {string=} type Effect type, from this.PROPERTY_EFFECT_TYPES - * @return {boolean} True if the prototype/instance has an effect of this type + * @return {boolean} True if the prototype/instance has an effect of this + * type * @protected */ _hasPropertyEffect(property, type) { @@ -1251,8 +1261,10 @@ export const PropertyEffects = dedupingMixin(superClass => { * Returns whether the current prototype/instance has a "read only" * accessor for the given property. * + * @override * @param {string} property Property name - * @return {boolean} True if the prototype/instance has an effect of this type + * @return {boolean} True if the prototype/instance has an effect of this + * type * @protected */ _hasReadOnlyEffect(property) { @@ -1263,8 +1275,10 @@ export const PropertyEffects = dedupingMixin(superClass => { * Returns whether the current prototype/instance has a "notify" * property effect for the given property. * + * @override * @param {string} property Property name - * @return {boolean} True if the prototype/instance has an effect of this type + * @return {boolean} True if the prototype/instance has an effect of this + * type * @protected */ _hasNotifyEffect(property) { @@ -1272,11 +1286,13 @@ export const PropertyEffects = dedupingMixin(superClass => { } /** - * Returns whether the current prototype/instance has a "reflect to attribute" - * property effect for the given property. + * Returns whether the current prototype/instance has a "reflect to + * attribute" property effect for the given property. * + * @override * @param {string} property Property name - * @return {boolean} True if the prototype/instance has an effect of this type + * @return {boolean} True if the prototype/instance has an effect of this + * type * @protected */ _hasReflectEffect(property) { @@ -1287,8 +1303,10 @@ export const PropertyEffects = dedupingMixin(superClass => { * Returns whether the current prototype/instance has a "computed" * property effect for the given property. * + * @override * @param {string} property Property name - * @return {boolean} True if the prototype/instance has an effect of this type + * @return {boolean} True if the prototype/instance has an effect of this + * type * @protected */ _hasComputedEffect(property) { @@ -1312,6 +1330,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * `path` can be a path string or array of path parts as accepted by the * public API. * + * @override * @param {string | !Array} path Path to set * @param {*} value Value to set * @param {boolean=} shouldNotify Set to true if this change should @@ -1346,7 +1365,7 @@ export const PropertyEffects = dedupingMixin(superClass => { } this.__dataHasPaths = true; if (this._setPendingProperty(/**@type{string}*/(path), value, shouldNotify)) { - computeLinkedPaths(this, path, value); + computeLinkedPaths(this, /**@type{string}*/ (path), value); return true; } } else { @@ -1374,6 +1393,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * * Users may override this method to provide alternate approaches. * + * @override * @param {!Node} node The node to set a property on * @param {string} prop The property to set * @param {*} value The value to set @@ -1491,6 +1511,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * pending property changes can later be flushed via a call to * `_flushClients`. * + * @override * @param {Object} client PropertyEffects client to enqueue * @return {void} * @protected @@ -1505,6 +1526,7 @@ export const PropertyEffects = dedupingMixin(superClass => { /** * Overrides superclass implementation. * + * @override * @return {void} * @protected */ @@ -1518,6 +1540,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Flushes any clients previously enqueued via `_enqueueClient`, causing * their `_flushProperties` method to run. * + * @override * @return {void} * @protected */ @@ -1566,6 +1589,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * `_flushProperties` call on client dom and before any element * observers are called. * + * @override * @return {void} * @protected */ @@ -1580,6 +1604,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Property names must be simple properties, not paths. Batched * path propagation is not supported. * + * @override * @param {Object} props Bag of one or more key-value pairs whose key is * a property and value is the new value to set for that property. * @param {boolean=} setReadOnly When true, any private values set in @@ -1634,6 +1659,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Runs each class of effects for the batch of changed properties in * a specific order (compute, propagate, reflect, observe, notify). * + * @override * @param {!Object} currentProps Bag of all current accessor values * @param {?Object} changedProps Bag of properties changed since the last * call to `_propertiesChanged` @@ -1680,6 +1706,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Called to propagate any property changes to stamped template nodes * managed by this element. * + * @override * @param {Object} changedProps Bag of changed properties * @param {Object} oldProps Bag of previous values for changed properties * @param {boolean} hasPaths True with `props` contains one or more paths @@ -1702,6 +1729,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Aliases one data path as another, such that path notifications from one * are routed to the other. * + * @override * @param {string | !Array} to Target path to link. * @param {string | !Array} from Source path to link. * @return {void} @@ -1720,6 +1748,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Note, the path to unlink should be the target (`to`) used when * linking the paths. * + * @override * @param {string | !Array} path Target path to unlink. * @return {void} * @public @@ -1741,8 +1770,10 @@ export const PropertyEffects = dedupingMixin(superClass => { * this.items.splice(1, 1, {name: 'Sam'}); * this.items.push({name: 'Bob'}); * this.notifySplices('items', [ - * { index: 1, removed: [{name: 'Todd'}], addedCount: 1, object: this.items, type: 'splice' }, - * { index: 3, removed: [], addedCount: 1, object: this.items, type: 'splice'} + * { index: 1, removed: [{name: 'Todd'}], addedCount: 1, + * object: this.items, type: 'splice' }, + * { index: 3, removed: [], addedCount: 1, + * object: this.items, type: 'splice'} * ]); * * @param {string} path Path that should be notified. @@ -1758,9 +1789,11 @@ export const PropertyEffects = dedupingMixin(superClass => { * Note that splice records _must_ be normalized such that they are * reported in index order (raw results from `Object.observe` are not * ordered and must be normalized/merged before notifying). + * + * @override * @return {void} * @public - */ + */ notifySplices(path, splices) { let info = {path: ''}; let array = /** @type {Array} */(get(this, path, info)); @@ -1774,6 +1807,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * `undefined` (this method does not throw when dereferencing undefined * paths). * + * @override * @param {(string|!Array<(string|number)>)} path Path to the value * to read. The path may be specified as a string (e.g. `foo.bar.baz`) * or an array of path parts (e.g. `['foo.bar', 'baz']`). Note that @@ -1798,6 +1832,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * this method does nothing (this method does not throw when * dereferencing undefined paths). * + * @override * @param {(string|!Array<(string|number)>)} path Path to the value * to write. The path may be specified as a string (e.g. `'foo.bar.baz'`) * or an array of path parts (e.g. `['foo.bar', 'baz']`). Note that @@ -1810,7 +1845,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * When specified, no notification will occur. * @return {void} * @public - */ + */ set(path, value, root) { if (root) { set(root, path, value); @@ -1832,6 +1867,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * This method notifies other paths to the same array that a * splice occurred to the array. * + * @override * @param {string | !Array} path Path to array. * @param {...*} items Items to push onto array * @return {number} New length of the array. @@ -1857,6 +1893,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * This method notifies other paths to the same array that a * splice occurred to the array. * + * @override * @param {string | !Array} path Path to array. * @return {*} Item that was removed. * @public @@ -1882,6 +1919,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * This method notifies other paths to the same array that a * splice occurred to the array. * + * @override * @param {string | !Array} path Path to array. * @param {number} start Index from which to start removing/inserting. * @param {number=} deleteCount Number of items to remove. @@ -1937,6 +1975,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * This method notifies other paths to the same array that a * splice occurred to the array. * + * @override * @param {string | !Array} path Path to array. * @return {*} Item that was removed. * @public @@ -1961,6 +2000,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * This method notifies other paths to the same array that a * splice occurred to the array. * + * @override * @param {string | !Array} path Path to array. * @param {...*} items Items to insert info array * @return {number} New length of the array. @@ -1984,11 +2024,12 @@ export const PropertyEffects = dedupingMixin(superClass => { * this.item.user.name = 'Bob'; * this.notifyPath('item.user.name'); * + * @override * @param {string} path Path that should be notified. * @param {*=} value Value at the path (optional). * @return {void} * @public - */ + */ notifyPath(path, value) { /** @type {string} */ let propPath; @@ -2013,6 +2054,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Property name * @param {boolean=} protectedSetter Creates a custom protected setter * when `true`. @@ -2033,8 +2075,10 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Property name - * @param {string|function(*,*)} method Function or name of observer method to call + * @param {string|function(*,*)} method Function or name of observer method + * to call * @param {boolean=} dynamicFn Whether the method name should be included as * a dependency to the effect. * @return {void} @@ -2057,6 +2101,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating * whether method names should be included as a dependency to the effect. @@ -2076,6 +2121,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Property name * @return {void} * @protected @@ -2095,6 +2141,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Property name * @return {void} * @protected @@ -2120,6 +2167,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * an instance to add effects at runtime. See that method for * full API docs. * + * @override * @param {string} property Name of computed property to set * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating @@ -2335,6 +2383,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * create and link an instance of the template metadata associated with a * particular stamping. * + * @override * @param {!HTMLTemplateElement} template Template containing binding * bindings * @param {boolean=} instanceBinding When false (default), performs @@ -2444,6 +2493,7 @@ export const PropertyEffects = dedupingMixin(superClass => { * Removes and unbinds the nodes previously contained in the provided * DocumentFragment returned from `_stampTemplate`. * + * @override * @param {!StampedTemplate} dom DocumentFragment previously returned * from `_stampTemplate` associated with the nodes to be removed * @return {void} @@ -2710,8 +2760,8 @@ export const PropertyEffects = dedupingMixin(superClass => { * Called to evaluate a previously parsed binding part based on a set of * one or more changed dependencies. * - * @param {this} inst Element that should be used as scope for - * binding dependencies + * @param {!Polymer_PropertyEffects} inst Element that should be used as + * scope for binding dependencies * @param {BindingPart} part Binding part metadata * @param {string} path Property/path that triggered this effect * @param {Object} props Bag of current property changes @@ -2741,9 +2791,6 @@ export const PropertyEffects = dedupingMixin(superClass => { } - // make a typing for closure :P - PropertyEffectsType = PropertyEffects; - return PropertyEffects; }); diff --git a/lib/utils/style-gather.js b/lib/utils/style-gather.js index 985802b70e..b67fcafd90 100644 --- a/lib/utils/style-gather.js +++ b/lib/utils/style-gather.js @@ -102,7 +102,7 @@ export function stylesFromModule(moduleId) { * Returns the `