diff --git a/types/lib/elements/array-selector.d.ts b/types/lib/elements/array-selector.d.ts index 81ffc584e3..9a66af0e99 100644 --- a/types/lib/elements/array-selector.d.ts +++ b/types/lib/elements/array-selector.d.ts @@ -37,33 +37,33 @@ declare namespace Polymer { /** * An array containing items from which selection will be made. */ - items: any[]|null; + items: any[]|null|undefined; /** * When `true`, multiple items may be selected at once (in this case, * `selected` is an array of currently selected items). When `false`, * only one item may be selected at a time. */ - multi: boolean; + multi: boolean|null|undefined; /** * 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. */ - selected: Object|Object[]|null; + selected: object|object[]|null; /** * When `multi` is false, this is the currently selected item, or `null` * if no item is selected. */ - selectedItem: Object|null; + selectedItem: object|null; /** * When `true`, calling `select` on an item that is already selected * will deselect the item. */ - toggle: boolean; + toggle: boolean|null|undefined; /** * Clears the selection state. diff --git a/types/lib/elements/dom-if.d.ts b/types/lib/elements/dom-if.d.ts index 67fd3c9a0e..7507dbee39 100644 --- a/types/lib/elements/dom-if.d.ts +++ b/types/lib/elements/dom-if.d.ts @@ -35,7 +35,7 @@ declare namespace Polymer { /** * A boolean indicating whether this template should stamp. */ - if: boolean; + if: boolean|null|undefined; /** * When true, elements will be removed from DOM and discarded when `if` @@ -44,7 +44,7 @@ declare namespace Polymer { * in the DOM when `if` becomes false, which is generally results * in better performance. */ - restamp: boolean; + restamp: boolean|null|undefined; connectedCallback(): any; disconnectedCallback(): any; diff --git a/types/lib/elements/dom-module.d.ts b/types/lib/elements/dom-module.d.ts index dabea1711e..bbeccc111b 100644 --- a/types/lib/elements/dom-module.d.ts +++ b/types/lib/elements/dom-module.d.ts @@ -33,7 +33,13 @@ declare namespace Polymer { * let img = customElements.get('dom-module').import('foo', 'img'); */ class DomModule extends HTMLElement { - attributeChangedCallback(name: string, old: any, value: any): void; + + /** + * @param name Name of attribute. + * @param old Old value of attribute. + * @param value Current value of attribute. + */ + attributeChangedCallback(name: string, old: string|null, value: string|null): void; /** * Registers the dom-module at a given id. This method should only be called diff --git a/types/lib/elements/dom-repeat.d.ts b/types/lib/elements/dom-repeat.d.ts index abbbe04823..723c074c3c 100644 --- a/types/lib/elements/dom-repeat.d.ts +++ b/types/lib/elements/dom-repeat.d.ts @@ -111,13 +111,13 @@ declare namespace Polymer { * An array containing items determining how many instances of the template * to stamp and that that each template instance should bind to. */ - items: any[]|null; + items: any[]|null|undefined; /** * The name of the variable to add to the binding scope for the array * element associated with a given template instance. */ - as: string; + as: string|null|undefined; /** * The name of the variable to add to the binding scope with the index @@ -125,7 +125,7 @@ declare namespace Polymer { * Note, for the index in the `this.items` array, use the value of the * `itemsIndexAs` property. */ - indexAs: string; + indexAs: string|null|undefined; /** * The name of the variable to add to the binding scope with the index @@ -133,7 +133,7 @@ declare namespace Polymer { * this instance in the sorted and filtered list of rendered items, * use the value of the `indexAs` property. */ - itemsIndexAs: string; + itemsIndexAs: string|null|undefined; /** * A function that should determine the sort order of the items. This @@ -142,7 +142,7 @@ declare namespace Polymer { * function should match the sort function passed to `Array.sort`. * Using a sort function has no effect on the underlying `items` array. */ - sort: Function|null; + sort: Function|null|undefined; /** * A function that can be used to filter items out of the view. This @@ -151,7 +151,7 @@ declare namespace Polymer { * function should match the sort function passed to `Array.filter`. * Using a filter function has no effect on the underlying `items` array. */ - filter: Function|null; + filter: Function|null|undefined; /** * When using a `filter` or `sort` function, the `observe` property @@ -160,7 +160,7 @@ declare namespace Polymer { * These should generally be fields of `item` that the sort or filter * function depends on. */ - observe: string; + observe: string|null|undefined; /** * When using a `filter` or `sort` function, the `delay` property @@ -169,14 +169,14 @@ declare namespace Polymer { * This is useful in rate-limiting shuffling of the view when * item changes may be frequent. */ - delay: number; + delay: number|null|undefined; /** * Count of currently rendered items after `filter` (if any) has been applied. * If "chunking mode" is enabled, `renderedItemCount` is updated each time a * set of template instances is rendered. */ - renderedItemCount: number; + renderedItemCount: number|null|undefined; /** * Defines an initial count of template instances to render after setting @@ -185,7 +185,7 @@ declare namespace Polymer { * incrementally at each animation frame therof until all instances have * been rendered. */ - initialCount: number; + initialCount: number|null|undefined; /** * When `initialCount` is used, this property defines a frame rate (in @@ -199,8 +199,8 @@ declare namespace Polymer { * throughput for event handlers and other tasks, but results in a * longer time for the remaining items to complete rendering. */ - targetFramerate: number; - _targetFrameTime: number; + targetFramerate: number|null|undefined; + _targetFrameTime: number|null|undefined; disconnectedCallback(): any; connectedCallback(): any; diff --git a/types/lib/legacy/class.d.ts b/types/lib/legacy/class.d.ts index d84880e22b..832e025dce 100644 --- a/types/lib/legacy/class.d.ts +++ b/types/lib/legacy/class.d.ts @@ -23,7 +23,7 @@ declare namespace Polymer { * @returns Returns a new Element class extended by the * passed in `behaviors` and also by `Polymer.LegacyElementMixin`. */ - function mixinBehaviors(behaviors: Object|any[]|null, klass: HTMLElement|{new(): HTMLElement}): {new(): HTMLElement}; + function mixinBehaviors(behaviors: object|any[]|null, klass: HTMLElement|{new(): HTMLElement}): {new(): HTMLElement}; /** diff --git a/types/lib/legacy/legacy-element-mixin.d.ts b/types/lib/legacy/legacy-element-mixin.d.ts index d834010aa5..70c69e317f 100644 --- a/types/lib/legacy/legacy-element-mixin.d.ts +++ b/types/lib/legacy/legacy-element-mixin.d.ts @@ -34,14 +34,10 @@ declare namespace Polymer { _debouncers: any; /** - * Provides an override implementation of `attributeChangedCallback` - * which adds the Polymer legacy API's `attributeChanged` method. - * - * @param name Name of attribute. - * @param old Old value of attribute. - * @param value Current value of attribute. + * Overrides the default `Polymer.PropertyEffects` implementation to + * add support for installing `hostAttributes` and `listeners`. */ - attributeChangedCallback(name: string, old: string|null, value: string|null): void; + ready(): any; /** * Overrides the default `Polymer.PropertyEffects` implementation to @@ -51,10 +47,14 @@ declare namespace Polymer { _initializeProperties(): any; /** - * Overrides the default `Polymer.PropertyEffects` implementation to - * add support for installing `hostAttributes` and `listeners`. + * Provides an override implementation of `attributeChangedCallback` + * which adds the Polymer legacy API's `attributeChanged` method. + * + * @param name Name of attribute. + * @param old Old value of attribute. + * @param value Current value of attribute. */ - ready(): any; + attributeChangedCallback(name: string, old: string|null, value: string|null): void; /** * Provides an implementation of `connectedCallback` @@ -187,7 +187,7 @@ declare namespace Polymer { * @param api Source object to copy properties from. * @returns prototype object that was passed as first argument. */ - extend(prototype: Object|null, api: Object|null): Object|null; + extend(prototype: object|null, api: object|null): object|null; /** * Copies props from a source object to a target object. @@ -200,7 +200,7 @@ declare namespace Polymer { * @param source Source object to copy properties from. * @returns Target object that was passed as first argument. */ - mixin(target: Object|null, source: Object|null): Object|null; + mixin(target: object|null, source: object|null): object|null; /** * Sets the prototype of an object. @@ -214,7 +214,7 @@ declare namespace Polymer { * @returns Returns the given `object` with its prototype set * to the given `prototype` object. */ - chainObject(object: Object|null, prototype: Object|null): Object|null; + chainObject(object: object|null, prototype: object|null): object|null; /** * Calls `importNode` on the `content` of the `template` specified and @@ -435,7 +435,7 @@ declare namespace Polymer { * `flush()` immediately invokes the debounced callback if the debouncer * is active. */ - debounce(jobName: string, callback: () => void, wait: number): Object|null; + debounce(jobName: string, callback: () => void, wait: number): object|null; /** * Returns whether a named debouncer is active. @@ -489,7 +489,7 @@ declare namespace Polymer { * instance. * @returns Newly created and configured element. */ - create(tag: string, props: Object|null): Element|null; + create(tag: string, props: object|null): Element|null; /** * Convenience method for importing an HTML document imperatively. diff --git a/types/lib/legacy/mutable-data-behavior.d.ts b/types/lib/legacy/mutable-data-behavior.d.ts index fad6fa58b4..67c7f5d50e 100644 --- a/types/lib/legacy/mutable-data-behavior.d.ts +++ b/types/lib/legacy/mutable-data-behavior.d.ts @@ -108,7 +108,7 @@ declare namespace Polymer { * for this element. When true, Objects and Arrays will skip dirty * checking, otherwise strict equality checking will be used. */ - mutableData: boolean; + mutableData: boolean|null|undefined; /** * Overrides `Polymer.PropertyEffects` to skip strict equality checking diff --git a/types/lib/legacy/polymer.dom.d.ts b/types/lib/legacy/polymer.dom.d.ts index e06dfaf5b3..49465a50b0 100644 --- a/types/lib/legacy/polymer.dom.d.ts +++ b/types/lib/legacy/polymer.dom.d.ts @@ -32,7 +32,7 @@ declare namespace Polymer { * * @returns True if node matched selector */ - function matchesSelector(node: Element, selector: string): boolean; + function matchesSelector(node: Node, selector: string): boolean; } /** diff --git a/types/lib/legacy/templatizer-behavior.d.ts b/types/lib/legacy/templatizer-behavior.d.ts index b59cacd0f4..412a5b9609 100644 --- a/types/lib/legacy/templatizer-behavior.d.ts +++ b/types/lib/legacy/templatizer-behavior.d.ts @@ -97,7 +97,7 @@ declare namespace Polymer { * @returns Returns the created instance of * the template prepared by `templatize`. */ - stamp(model?: Object|null): TemplateInstanceBase|null; + stamp(model?: object|null): TemplateInstanceBase|null; /** * Returns the template "model" (`TemplateInstance`) associated with diff --git a/types/lib/mixins/element-mixin.d.ts b/types/lib/mixins/element-mixin.d.ts index 91e243428f..d6e4bb76ee 100644 --- a/types/lib/mixins/element-mixin.d.ts +++ b/types/lib/mixins/element-mixin.d.ts @@ -11,11 +11,11 @@ /// /// /// -/// /// /// /// /// +/// declare namespace Polymer { @@ -76,7 +76,7 @@ declare namespace Polymer { * of dash-cased attributes based on `properties`) */ function ElementMixin {}>(base: T): { - new(...args: any[]): ElementMixin & Polymer.PropertyEffects + new(...args: any[]): ElementMixin & Polymer.PropertyEffects & Polymer.PropertiesMixin } & T interface ElementMixin { @@ -88,19 +88,9 @@ declare namespace Polymer { $: any; /** - * Provides a default implementation of the standard Custom Elements - * `attributeChangedCallback`. - * - * By default, attributes declared in `properties` metadata are - * deserialized using their `type` information to properties of the - * same name. "Dash-cased" attributes are deserialized to "camelCase" - * properties. - * - * @param name Name of attribute. - * @param old Old value of attribute. - * @param value Current value of attribute. + * Stamps the element template. */ - attributeChangedCallback(name: string, old: string|null, value: string|null): any; + ready(): any; /** * Overrides the default `Polymer.PropertyAccessors` to ensure class @@ -112,11 +102,6 @@ declare namespace Polymer { */ _initializeProperties(): any; - /** - * Stamps the element template. - */ - ready(): any; - /** * Implements `PropertyEffects`'s `_readyClients` call. Attaches * element dom by calling `_attachDom` with the dom stamped from the @@ -136,12 +121,6 @@ declare namespace Polymer { */ connectedCallback(): any; - /** - * Provides a default implementation of the standard Custom Elements - * `disconnectedCallback`. - */ - disconnectedCallback(): any; - /** * Attaches an element's stamped dom to itself. By default, * this method creates a `shadowRoot` and adds the dom to it. @@ -169,7 +148,7 @@ declare namespace Polymer { * @param properties Bag of custom property key/values to * apply to this element. */ - updateStyles(properties?: Object|null): void; + updateStyles(properties?: object|null): void; /** * Rewrites a given URL relative to a base URL. The base URL defaults to diff --git a/types/lib/mixins/mutable-data.d.ts b/types/lib/mixins/mutable-data.d.ts index 9c01002076..6788d46d94 100644 --- a/types/lib/mixins/mutable-data.d.ts +++ b/types/lib/mixins/mutable-data.d.ts @@ -117,7 +117,7 @@ declare namespace Polymer { * for this element. When true, Objects and Arrays will skip dirty * checking, otherwise strict equality checking will be used. */ - mutableData: boolean; + mutableData: boolean|null|undefined; /** * Overrides `Polymer.PropertyEffects` to provide option for skipping diff --git a/types/lib/mixins/properties-changed.d.ts b/types/lib/mixins/properties-changed.d.ts new file mode 100644 index 0000000000..4dabca1f14 --- /dev/null +++ b/types/lib/mixins/properties-changed.d.ts @@ -0,0 +1,257 @@ +/** + * DO NOT EDIT + * + * This file was automatically generated by + * https://github.com/Polymer/gen-typescript-declarations + * + * To modify these typings, edit the source file(s): + * lib/mixins/properties-changed.html + */ + +/// +/// +/// + +declare namespace Polymer { + + /** + * Element class mixin that provides basic meta-programming for creating one + * or more property accessors (getter/setter pair) that enqueue an async + * (batched) `_propertiesChanged` callback. + * + * For basic usage of this mixin, simply declare attributes to observe via + * the standard `static get observedAttributes()`, implement `_propertiesChanged` + * on the class, and then call `MyClass.createPropertiesForAttributes()` once + * on the class to generate property accessors for each observed attribute + * prior to instancing. Last, call `this._enableProperties()` in the element's + * `connectedCallback` to enable the accessors. + * + * Any `observedAttributes` will automatically be + * deserialized via `attributeChangedCallback` and set to the associated + * property using `dash-case`-to-`camelCase` convention. + */ + function PropertiesChanged {}>(base: T): { + new(...args: any[]): PropertiesChanged + } & T + + interface PropertiesChanged { + + /** + * Creates a setter/getter pair for the named property with its own + * local storage. The getter returns the value in the local storage, + * and the setter calls `_setProperty`, which updates the local storage + * for the property and enqueues a `_propertiesChanged` callback. + * + * This method may be called on a prototype or an instance. Calling + * this method may overwrite a property value that already exists on + * the prototype/instance by creating the accessor. + * + * @param property Name of the property + * @param readOnly When true, no setter is created; the + * protected `_setProperty` function must be used to set the property + */ + _createPropertyAccessor(property: string, readOnly?: boolean): any; + + /** + * Defines a property accessor for the given property. + * + * @param property Name of the property + * @param readOnly When true, no setter is created + */ + _definePropertyAccessor(property: string, readOnly?: boolean): any; + + /** + * Lifecycle callback called when properties are enabled via + * `_enableProperties`. + * + * Users may override this function to implement behavior that is + * dependent on the element having its property data initialized, e.g. + * from defaults (initialized from `constructor`, `_initializeProperties`), + * `attributeChangedCallback`, or values propagated from host e.g. via + * bindings. `super.ready()` must be called to ensure the data system + * becomes enabled. + */ + ready(): any; + + /** + * Initializes the local storage for property accessors. + * + * Provided as an override point for performing any setup work prior + * to initializing the property accessor system. + */ + _initializeProperties(): any; + + /** + * Called at ready time with bag of instance properties that overwrote + * accessors when the element upgraded. + * + * The default implementation sets these properties back into the + * setter at ready time. This method is provided as an override + * point for customizing or providing more efficient initialization. + * + * @param props Bag of property values that were overwritten + * when creating property accessors. + */ + _initializeInstanceProperties(props: object|null): any; + + /** + * Updates the local storage for a property (via `_setPendingProperty`) + * and enqueues a `_proeprtiesChanged` callback. + * + * @param property Name of the property + * @param value Value to set + */ + _setProperty(property: string, value: any): any; + + /** + * Returns the value for the given property. + * + * @param property Name of property + * @returns Value for the given property + */ + _getProperty(property: string): any; + + /** + * Updates the local storage for a property, records the previous value, + * and adds it to the set of "pending changes" that will be passed to the + * `_propertiesChanged` callback. This method does not enqueue the + * `_propertiesChanged` callback. + * + * @param property Name of the property + * @param value Value to set + * @param ext Not used here; affordance for closure + * @returns Returns true if the property changed + */ + _setPendingProperty(property: string, value: any, ext?: boolean): boolean; + + /** + * Marks the properties as invalid, and enqueues an async + * `_propertiesChanged` callback. + */ + _invalidateProperties(): any; + + /** + * Call to enable property accessor processing. Before this method is + * called accessor values will be set but side effects are + * queued. When called, any pending side effects occur immediately. + * For elements, generally `connectedCallback` is a normal spot to do so. + * It is safe to call this method multiple times as it only turns on + * property accessors once. + */ + _enableProperties(): any; + + /** + * Calls the `_propertiesChanged` callback with the current set of + * pending changes (and old values recorded when pending changes were + * set), and resets the pending set of changes. Generally, this method + * should not be called in user code. + */ + _flushProperties(): any; + + /** + * Callback called when any properties with accessors created via + * `_createPropertyAccessor` have been set. + * + * @param currentProps Bag of all current accessor values + * @param changedProps Bag of properties changed since the last + * call to `_propertiesChanged` + * @param oldProps Bag of previous values for each property + * in `changedProps` + */ + _propertiesChanged(currentProps: object, changedProps: object, oldProps: object): any; + + /** + * Method called to determine whether a property value should be + * considered as a change and cause the `_propertiesChanged` callback + * to be enqueued. + * + * The default implementation returns `true` for primitive types if a + * strict equality check fails, and returns `true` for all Object/Arrays. + * The method always returns false for `NaN`. + * + * Override this method to e.g. provide stricter checking for + * Objects/Arrays when using immutable patterns. + * + * @param property Property name + * @param value New property value + * @param old Previous property value + * @returns Whether the property should be considered a change + * and enqueue a `_proeprtiesChanged` callback + */ + _shouldPropertyChange(property: string, value: any, old: any): boolean; + + /** + * Implements native Custom Elements `attributeChangedCallback` to + * set an attribute value to a property via `_attributeToProperty`. + * + * @param name Name of attribute that changed + * @param old Old attribute value + * @param value New attribute value + */ + attributeChangedCallback(name: string, old: string|null, value: string|null): any; + + /** + * Deserializes an attribute to its associated property. + * + * This method calls the `_deserializeValue` method to convert the string to + * a typed value. + * + * @param attribute Name of attribute to deserialize. + * @param value of the attribute. + * @param type type to deserialize to, defaults to the value + * returned from `typeForProperty` + */ + _attributeToProperty(attribute: string, value: string|null, type?: any): any; + + /** + * Serializes a property to its associated attribute. + * + * @param property Property name to reflect. + * @param attribute Attribute name to reflect to. + * @param value Property value to refect. + */ + _propertyToAttribute(property: string, attribute?: string, value?: any): any; + + /** + * Sets a typed value to an HTML attribute on a node. + * + * This method calls the `_serializeValue` method to convert the typed + * value to a string. If the `_serializeValue` method returns `undefined`, + * the attribute will be removed (this is the default for boolean + * type `false`). + * + * @param node Element to set attribute to. + * @param value Value to serialize. + * @param attribute Attribute name to serialize to. + */ + _valueToNodeAttribute(node: Element|null, value: any, attribute: string): any; + + /** + * Converts a typed JavaScript value to a string. + * + * This method is called by Polymer when setting JS property values to + * HTML attributes. Users may override this method on Polymer element + * prototypes to provide serialization for custom types. + * + * @param value Property value to serialize. + * @returns String serialized from the provided + * property value. + */ + _serializeValue(value: any): string|undefined; + + /** + * Converts a string to a typed JavaScript value. + * + * This method is called when reading HTML attribute values to + * JS properties. Users may override this method to provide + * deserialization for custom `type`s. The given `type` is executed + * as a function with the value as an argument. The `Boolean` `type` + * is specially handled such that an empty string returns true. + * + * @param value Value to deserialize. + * @param type Type to deserialize the string to. + * @returns Typed value deserialized from the provided string. + */ + _deserializeValue(value: string|null, type?: any): any; + } +} diff --git a/types/lib/mixins/properties-mixin.d.ts b/types/lib/mixins/properties-mixin.d.ts new file mode 100644 index 0000000000..d31e89cd3b --- /dev/null +++ b/types/lib/mixins/properties-mixin.d.ts @@ -0,0 +1,52 @@ +/** + * DO NOT EDIT + * + * This file was automatically generated by + * https://github.com/Polymer/gen-typescript-declarations + * + * To modify these typings, edit the source file(s): + * lib/mixins/properties-mixin.html + */ + +/// +/// +/// + +declare namespace Polymer { + + /** + * Mixin that provides a minimal starting point to using the PropertiesChanged + * mixin by providing a mechanism to declare properties in a static + * getter (e.g. static get properties() { return { foo: String } }). Changes + * are reported via the `_propertiesChanged` method. + * + * This mixin provides no specific support for rendering. Users are expected + * to create a ShadowRoot and put content into it and update it in whatever + * way makes sense. This can be done in reaction to properties changing by + * implementing `_propertiesChanged`. + */ + function PropertiesMixin {}>(base: T): { + new(...args: any[]): PropertiesMixin & Polymer.PropertiesChanged + } & T + + interface PropertiesMixin { + + /** + * Overrides `PropertiesChanged` method and adds a call to + * `finalize` which lazily configures the element's property accessors. + */ + _initializeProperties(): any; + + /** + * Called when the element is added to a document. + * Calls `_enableProperties` to turn on property system from + * `PropertiesChanged`. + */ + connectedCallback(): any; + + /** + * Called when the element is removed from a document + */ + disconnectedCallback(): any; + } +} diff --git a/types/lib/mixins/property-accessors.d.ts b/types/lib/mixins/property-accessors.d.ts index a62eabc39e..c0db6b965a 100644 --- a/types/lib/mixins/property-accessors.d.ts +++ b/types/lib/mixins/property-accessors.d.ts @@ -11,7 +11,7 @@ /// /// /// -/// +/// declare namespace Polymer { @@ -32,105 +32,36 @@ declare namespace Polymer { * property using `dash-case`-to-`camelCase` convention. */ function PropertyAccessors {}>(base: T): { - new(...args: any[]): PropertyAccessors + new(...args: any[]): PropertyAccessors & Polymer.PropertiesChanged } & T interface PropertyAccessors { /** - * Implements native Custom Elements `attributeChangedCallback` to - * set an attribute value to a property via `_attributeToProperty`. + * Overrides PropertiesChanged implementation to save existing prototype + * property value so that it can be reset. * - * @param name Name of attribute that changed - * @param old Old attribute value - * @param value New attribute value - */ - attributeChangedCallback(name: string, old: string|null, value: string|null): any; - - /** - * Initializes the local storage for property accessors. - * - * Provided as an override point for performing any setup work prior - * to initializing the property accessor system. - */ - _initializeProperties(): void; - - /** - * Called at instance time with bag of properties that were overwritten - * by accessors on the prototype when accessors were created. - * - * The default implementation sets these properties back into the - * setter at instance time. This method is provided as an override - * point for customizing or providing more efficient initialization. - * - * @param props Bag of property values that were overwritten - * when creating property accessors. - */ - _initializeProtoProperties(props: Object|null): void; - - /** - * Called at ready time with bag of instance properties that overwrote - * accessors when the element upgraded. - * - * The default implementation sets these properties back into the - * setter at ready time. This method is provided as an override - * point for customizing or providing more efficient initialization. - * - * @param props Bag of property values that were overwritten - * when creating property accessors. - */ - _initializeInstanceProperties(props: Object|null): void; - - /** - * Ensures the element has the given attribute. If it does not, - * assigns the given value to the attribute. - * - * @param attribute Name of attribute to ensure is set. - * @param value of the attribute. - */ - _ensureAttribute(attribute: string, value: string): void; - - /** - * Deserializes an attribute to its associated property. - * - * This method calls the `_deserializeValue` method to convert the string to - * a typed value. + * @param property Name of the property + * @param readOnly When true, no setter is created * - * @param attribute Name of attribute to deserialize. - * @param value of the attribute. - * @param type type to deserialize to. + * When calling on a prototype, any overwritten values are saved in + * `__dataProto`, and it is up to the subclasser to decide how/when + * to set those properties back into the accessor. When calling on an + * instance, the overwritten value is set via `_setPendingProperty`, + * and the user should call `_invalidateProperties` or `_flushProperties` + * for the values to take effect. */ - _attributeToProperty(attribute: string, value: string|null, type?: any): void; + _definePropertyAccessor(property: string, readOnly?: boolean): void; /** - * Serializes a property to its associated attribute. - * - * @param property Property name to reflect. - * @param attribute Attribute name to reflect. - * @param value Property value to refect. + * Overrides PropertiesChanged implementation to initialize values for + * accessors created for values that already existed on the element + * prototype. */ - _propertyToAttribute(property: string, attribute?: string, value?: any): void; - - /** - * Sets a typed value to an HTML attribute on a node. - * - * This method calls the `_serializeValue` method to convert the typed - * value to a string. If the `_serializeValue` method returns `undefined`, - * the attribute will be removed (this is the default for boolean - * type `false`). - * - * @param node Element to set attribute to. - * @param value Value to serialize. - * @param attribute Attribute name to serialize to. - */ - _valueToNodeAttribute(node: Element|null, value: any, attribute: string): void; + _initializeProperties(): void; /** - * Converts a typed JavaScript value to a string. - * - * This method is called by Polymer when setting JS property values to - * HTML attributes. Users may override this method on Polymer element - * prototypes to provide serialization for custom types. + * Overrides PropertiesChanged implemention to serialize objects as JSON. * * @param value Property value to serialize. * @returns String serialized from the provided property value. @@ -147,9 +78,6 @@ declare namespace Polymer { * `properties` configuration object for a given property, and is * by convention the constructor for the type to deserialize. * - * Note: The return value of `undefined` is used as a sentinel value to - * indicate the attribute should be removed. - * * @param value Attribute value to deserialize. * @param type Type to deserialize the string to. * @returns Typed value deserialized from the provided string. @@ -157,55 +85,34 @@ declare namespace Polymer { _deserializeValue(value: string|null, type?: any): any; /** - * Creates a setter/getter pair for the named property with its own - * local storage. The getter returns the value in the local storage, - * and the setter calls `_setProperty`, which updates the local storage - * for the property and enqueues a `_propertiesChanged` callback. - * - * This method may be called on a prototype or an instance. Calling - * this method may overwrite a property value that already exists on - * the prototype/instance by creating the accessor. When calling on - * a prototype, any overwritten values are saved in `__dataProto`, - * and it is up to the subclasser to decide how/when to set those - * properties back into the accessor. When calling on an instance, - * the overwritten value is set via `_setPendingProperty`, and the - * user should call `_invalidateProperties` or `_flushProperties` - * for the values to take effect. + * Called at instance time with bag of properties that were overwritten + * by accessors on the prototype when accessors were created. * - * @param property Name of the property - * @param readOnly When true, no setter is created; the - * protected `_setProperty` function must be used to set the property - */ - _createPropertyAccessor(property: string, readOnly?: boolean): void; - - /** - * Returns true if this library created an accessor for the given property. + * The default implementation sets these properties back into the + * setter at instance time. This method is provided as an override + * point for customizing or providing more efficient initialization. * - * @param property Property name - * @returns True if an accessor was created + * @param props Bag of property values that were overwritten + * when creating property accessors. */ - _hasAccessor(property: string): boolean; + _initializeProtoProperties(props: object|null): void; /** - * Updates the local storage for a property (via `_setPendingProperty`) - * and enqueues a `_propertiesChanged` callback. + * Ensures the element has the given attribute. If it does not, + * assigns the given value to the attribute. * - * @param property Name of the property - * @param value Value to set + * @param attribute Name of attribute to ensure is set. + * @param value of the attribute. */ - _setProperty(property: string, value: any): void; + _ensureAttribute(attribute: string, value: string): void; /** - * Updates the local storage for a property, records the previous value, - * and adds it to the set of "pending changes" that will be passed to the - * `_propertiesChanged` callback. This method does not enqueue the - * `_propertiesChanged` callback. + * Returns true if this library created an accessor for the given property. * - * @param property Name of the property - * @param value Value to set - * @returns Returns true if the property changed + * @param property Property name + * @returns True if an accessor was created */ - _setPendingProperty(property: string, value: any): boolean; + _hasAccessor(property: string): boolean; /** * Returns true if the specified property has a pending change. @@ -214,75 +121,5 @@ declare namespace Polymer { * @returns True if property has a pending change */ _isPropertyPending(prop: string): boolean; - - /** - * Marks the properties as invalid, and enqueues an async - * `_propertiesChanged` callback. - */ - _invalidateProperties(): void; - - /** - * Call to enable property accessor processing. Before this method is - * called accessor values will be set but side effects are - * queued. When called, any pending side effects occur immediately. - * For elements, generally `connectedCallback` is a normal spot to do so. - * It is safe to call this method multiple times as it only turns on - * property accessors once. - */ - _enableProperties(): void; - - /** - * Calls the `_propertiesChanged` callback with the current set of - * pending changes (and old values recorded when pending changes were - * set), and resets the pending set of changes. Generally, this method - * should not be called in user code. - */ - _flushProperties(): void; - - /** - * Lifecycle callback called the first time properties are being flushed. - * Prior to `ready`, all property sets through accessors are queued and - * their effects are flushed after this method returns. - * - * Users may override this function to implement behavior that is - * dependent on the element having its properties initialized, e.g. - * from defaults (initialized from `constructor`, `_initializeProperties`), - * `attributeChangedCallback`, or values propagated from host e.g. via - * bindings. `super.ready()` must be called to ensure the data system - * becomes enabled. - */ - ready(): any; - - /** - * Callback called when any properties with accessors created via - * `_createPropertyAccessor` have been set. - * - * @param currentProps Bag of all current accessor values - * @param changedProps Bag of properties changed since the last - * call to `_propertiesChanged` - * @param oldProps Bag of previous values for each property - * in `changedProps` - */ - _propertiesChanged(currentProps: Object, changedProps: Object, oldProps: Object): any; - - /** - * Method called to determine whether a property value should be - * considered as a change and cause the `_propertiesChanged` callback - * to be enqueued. - * - * The default implementation returns `true` for primitive types if a - * strict equality check fails, and returns `true` for all Object/Arrays. - * The method always returns false for `NaN`. - * - * Override this method to e.g. provide stricter checking for - * Objects/Arrays when using immutable patterns. - * - * @param property Property name - * @param value New property value - * @param old Previous property value - * @returns Whether the property should be considered a change - * and enqueue a `_propertiesChanged` callback - */ - _shouldPropertyChange(property: string, value: any, old: any): boolean; } } diff --git a/types/lib/mixins/property-effects.d.ts b/types/lib/mixins/property-effects.d.ts index c4a8d856f4..191ae6fb5d 100644 --- a/types/lib/mixins/property-effects.d.ts +++ b/types/lib/mixins/property-effects.d.ts @@ -70,16 +70,15 @@ declare namespace Polymer { * @returns Cloned template content */ _stampTemplate(template: HTMLTemplateElement): StampedTemplate; - _initializeProperties(): any; /** - * Overrides `Polymer.PropertyAccessors` implementation to provide a - * more efficient implementation of initializing properties from - * the prototype on the instance. - * - * @param props Properties to initialize on the prototype + * Overrides `PropertyAccessors` so that property accessor + * side effects are not enabled until after client dom is fully ready. + * Also calls `_flushClients` callback to ensure client dom is enabled + * that was not enabled as a result of flushing properties. */ - _initializeProtoProperties(props: Object|null): any; + ready(): any; + _initializeProperties(): any; /** * Overrides `Polymer.PropertyAccessors` implementation to avoid setting @@ -87,7 +86,7 @@ declare namespace Polymer { * * @param props Properties to initialize on the instance */ - _initializeInstanceProperties(props: Object|null): any; + _initializeInstanceProperties(props: object|null): any; /** * Overrides base implementation to ensure all accessors set `shouldNotify` @@ -96,7 +95,7 @@ declare namespace Polymer { _setProperty(property: any, value: any): any; /** - * Overrides the `PropertyAccessors` implementation to introduce special + * Overrides the `PropertiesChanged` implementation to introduce special * dirty check logic depending on the property & value being set: * * 1. Any value set to a path (e.g. 'obj.prop': 42 or 'obj.prop': {...}) @@ -140,12 +139,9 @@ declare namespace Polymer { _invalidateProperties(): any; /** - * Overrides `PropertyAccessors` so that property accessor - * side effects are not enabled until after client dom is fully ready. - * Also calls `_flushClients` callback to ensure client dom is enabled - * that was not enabled as a result of flushing properties. + * Overrides superclass implementation. */ - ready(): any; + _flushProperties(): any; /** * Implements `PropertyAccessors`'s properties changed callback. @@ -155,6 +151,15 @@ declare namespace Polymer { */ _propertiesChanged(currentProps: any, changedProps: any, oldProps: any): any; + /** + * Overrides `Polymer.PropertyAccessors` implementation to provide a + * more efficient implementation of initializing properties from + * the prototype on the instance. + * + * @param props Properties to initialize on the prototype + */ + _initializeProtoProperties(props: object|null): any; + /** * Equivalent to static `addPropertyEffect` API but can be called on * an instance to add effects at runtime. See that method for @@ -164,7 +169,7 @@ declare namespace Polymer { * @param type Effect type, from this.PROPERTY_EFFECT_TYPES * @param effect Effect metadata object */ - _addPropertyEffect(property: string, type: string, effect?: Object|null): void; + _addPropertyEffect(property: string, type: string, effect?: object|null): void; /** * Removes the given property effect. @@ -173,7 +178,7 @@ declare namespace Polymer { * @param type Effect type, from this.PROPERTY_EFFECT_TYPES * @param effect Effect metadata object to remove */ - _removePropertyEffect(property: string, type: string, effect?: Object|null): void; + _removePropertyEffect(property: string, type: string, effect?: object|null): void; /** * Returns whether the current prototype/instance has a property effect @@ -278,7 +283,7 @@ declare namespace Polymer { * * @param client PropertyEffects client to enqueue */ - _enqueueClient(client: Object|null): void; + _enqueueClient(client: object|null): void; /** * Flushes any clients previously enqueued via `_enqueueClient`, causing @@ -306,7 +311,7 @@ declare namespace Polymer { * `props` will be set. By default, `setProperties` will not set * `readOnly: true` root properties. */ - setProperties(props: Object|null, setReadOnly?: boolean): void; + setProperties(props: object|null, setReadOnly?: boolean): void; /** * Called to propagate any property changes to stamped template nodes @@ -316,7 +321,7 @@ declare namespace Polymer { * @param oldProps Bag of previous values for changed properties * @param hasPaths True with `props` contains one or more paths */ - _propagatePropertyChanges(changedProps: Object|null, oldProps: Object|null, hasPaths: boolean): void; + _propagatePropertyChanges(changedProps: object|null, oldProps: object|null, hasPaths: boolean): void; /** * Aliases one data path as another, such that path notifications from one @@ -385,7 +390,7 @@ declare namespace Polymer { * @returns Value at the path, or `undefined` if any part of the path * is undefined. */ - get(path: string|Array, root?: Object|null): any; + get(path: string|Array, root?: object|null): any; /** * Convenience method for setting a value to a path and notifying any @@ -406,7 +411,7 @@ declare namespace Polymer { * @param root Root object from which the path is evaluated. * When specified, no notification will occur. */ - set(path: string|Array, value: any, root?: Object|null): void; + set(path: string|Array, value: any, root?: object|null): void; /** * Adds items onto the end of the array at the path specified. @@ -529,7 +534,7 @@ declare namespace Polymer { * @param dynamicFn Boolean or object map indicating * whether method names should be included as a dependency to the effect. */ - _createMethodObserver(expression: string, dynamicFn?: boolean|Object|null): void; + _createMethodObserver(expression: string, dynamicFn?: boolean|object|null): void; /** * Equivalent to static `createNotifyingProperty` API but can be called on @@ -559,7 +564,7 @@ declare namespace Polymer { * @param dynamicFn Boolean or object map indicating * whether method names should be included as a dependency to the effect. */ - _createComputedProperty(property: string, expression: string, dynamicFn?: boolean|Object|null): void; + _createComputedProperty(property: string, expression: string, dynamicFn?: boolean|object|null): void; /** * Equivalent to static `bindTemplate` API but can be called on diff --git a/types/lib/utils/async.d.ts b/types/lib/utils/async.d.ts index bcc3a083e7..963d85af52 100644 --- a/types/lib/utils/async.d.ts +++ b/types/lib/utils/async.d.ts @@ -32,7 +32,7 @@ declare namespace Polymer { * * @returns An async timeout interface */ - function after(delay: number): AsyncInterface; + function after(delay?: number): AsyncInterface; /** @@ -40,7 +40,15 @@ declare namespace Polymer { * * @returns Handle used for canceling task */ - function run(fn: Function): number; + function run(fn: Function, delay?: number): number; + + + /** + * Enqueues a function called in the next task. + * + * @returns Handle used for canceling task + */ + function run(fn: Function, delay?: number): number; /** @@ -50,7 +58,7 @@ declare namespace Polymer { /** - * Cancels a previously enqueued `animationFrame` callback. + * Cancels a previously enqueued `timeOut` callback. */ function cancel(handle: number): void; } @@ -66,7 +74,27 @@ declare namespace Polymer { * * @returns Handle used for canceling task */ - function run(fn: Function): number; + function run(fn: (p0: number) => any): number; + + + /** + * Enqueues a function called at `requestAnimationFrame` timing. + * + * @returns Handle used for canceling task + */ + function run(fn: (p0: number) => any): number; + + + /** + * Cancels a previously enqueued `animationFrame` callback. + */ + function cancel(handle: number): void; + + + /** + * Cancels a previously enqueued `animationFrame` callback. + */ + function cancel(handle: number): void; } /** diff --git a/types/lib/utils/flattened-nodes-observer.d.ts b/types/lib/utils/flattened-nodes-observer.d.ts index 7c3324b84f..e6f5d2ed25 100644 --- a/types/lib/utils/flattened-nodes-observer.d.ts +++ b/types/lib/utils/flattened-nodes-observer.d.ts @@ -53,9 +53,6 @@ declare namespace Polymer { * ``` */ class FlattenedNodesObserver { - _shadyChildrenObserver: MutationObserver|null; - _nativeChildrenObserver: MutationObserver|null; - _boundSchedule: () => any; /** * Activates an observer. This method is automatically called when diff --git a/types/lib/utils/html-tag.d.ts b/types/lib/utils/html-tag.d.ts index 2a706b55a4..a3c879554c 100644 --- a/types/lib/utils/html-tag.d.ts +++ b/types/lib/utils/html-tag.d.ts @@ -37,5 +37,5 @@ declare namespace Polymer { * * @returns Constructed HTMLTemplateElement */ - function html(strings: string[], ...values: any[]): HTMLTemplateElement; + function html(strings: ITemplateArray|null, ...values: any[]): HTMLTemplateElement; } diff --git a/types/lib/utils/path.d.ts b/types/lib/utils/path.d.ts index 0231991faa..afcc5efbac 100644 --- a/types/lib/utils/path.d.ts +++ b/types/lib/utils/path.d.ts @@ -137,7 +137,7 @@ declare namespace Polymer { * @returns Value at path, or `undefined` if the path could not be * fully dereferenced. */ - function get(root: Object|null, path: string|Array, info?: Object|null): any; + function get(root: object|null, path: string|Array, info?: object|null): any; /** @@ -146,6 +146,6 @@ declare namespace Polymer { * * @returns The normalized version of the input path */ - function set(root: Object|null, path: string|Array, value: any): string|undefined; + function set(root: object|null, path: string|Array, value: any): string|undefined; } } diff --git a/types/lib/utils/templatize.d.ts b/types/lib/utils/templatize.d.ts index 077893d00a..dc866ad9cf 100644 --- a/types/lib/utils/templatize.d.ts +++ b/types/lib/utils/templatize.d.ts @@ -113,7 +113,7 @@ declare namespace Polymer { * @returns Generated class bound to the template * provided */ - function templatize(template: HTMLTemplateElement, owner: Polymer_PropertyEffects, options?: Object|null): {new(): TemplateInstanceBase}; + function templatize(template: HTMLTemplateElement, owner: Polymer_PropertyEffects, options?: object|null): {new(): TemplateInstanceBase}; /**