Fix type declarations inadvertedtly referencing Polymer.Element. (#5084)

Polymer defines its own `Element` class, shadowing the standard global `Element` class. This means that references to `Element` within the `Polymer` namespace inadvertently reference `Polymer.Element`. Here we define an alias of the global `Element`, so that we can reference it from declarations within the `Polymer` namespace. See microsoft/TypeScript#983 for general discussion of this shadowing problem in TypeScript. Fixes #5074
Polymer · Feb 1, 2018 · 82cd3da · 82cd3da
1 parent 86399df
commit 82cd3da
Show file tree

Hide file tree

Showing 10 changed files with 37 additions and 24 deletions.
diff --git a/gen-tsd.json b/gen-tsd.json
@@ -17,6 +17,7 @@
     ]
   },
   "renameTypes": {
-    "Polymer_PropertyEffects": "Polymer.PropertyEffects"
+    "Polymer_PropertyEffects": "Polymer.PropertyEffects",
+    "Element": "_Element"
   }
 }
diff --git a/types/extra-types.d.ts b/types/extra-types.d.ts
@@ -133,3 +133,15 @@ interface IdleDeadline {
   didTimeout: boolean;
   timeRemaining(): number;
 }
+
+/**
+ * Polymer defines its own `Element` class, shadowing the standard global
+ * `Element` class. This means that references to `Element` within the `Polymer`
+ * namespace inadvertently reference `Polymer.Element`. Here we define an alias
+ * of the global `Element`, so that we can reference it from declarations within
+ * the `Polymer` namespace.
+ *
+ * See https://github.com/Microsoft/TypeScript/issues/983 for general discussion
+ * of this shadowing problem in TypeScript.
+ */
+type _Element = Element;
diff --git a/types/lib/elements/dom-module.d.ts b/types/lib/elements/dom-module.d.ts
@@ -44,7 +44,7 @@ declare namespace Polymer {
      * @returns Returns the element which matches `selector` in the
      * module registered at the specified `id`.
      */
-    static import(id: string, selector?: string): Element|null;
+    static import(id: string, selector?: string): _Element|null;
 
     /**
      * @param name Name of attribute.

diff --git a/types/lib/legacy/legacy-element-mixin.d.ts b/types/lib/legacy/legacy-element-mixin.d.ts
@@ -187,7 +187,7 @@ declare namespace Polymer {
      * @param attribute Attribute name to serialize to.
      * @param node Element to set attribute to.
      */
-    serializeValueToAttribute(value: any, attribute: string, node: Element|null): void;
+    serializeValueToAttribute(value: any, attribute: string, node: _Element|null): void;
 
     /**
      * Copies own properties (including accessor descriptors) from a source
@@ -258,7 +258,7 @@ declare namespace Polymer {
      * @param eventName Name of event to listen for.
      * @param methodName Name of handler method on `this` to call.
      */
-    listen(node: Element|null, eventName: string, methodName: string): void;
+    listen(node: _Element|null, eventName: string, methodName: string): void;
 
     /**
      * Convenience method to remove an event listener from a given element,
@@ -269,7 +269,7 @@ declare namespace Polymer {
      * @param methodName Name of handler method on `this` to not call
      *        anymore.
      */
-    unlisten(node: Element|null, eventName: string, methodName: string): void;
+    unlisten(node: _Element|null, eventName: string, methodName: string): void;
 
     /**
      * Override scrolling behavior to all direction, one direction, or none.
@@ -285,7 +285,7 @@ declare namespace Polymer {
      * @param node Element to apply scroll direction setting.
      * Defaults to `this`.
      */
-    setScrollDirection(direction?: string, node?: Element|null): void;
+    setScrollDirection(direction?: string, node?: _Element|null): void;
 
     /**
      * Convenience method to run `querySelector` on this local DOM scope.
@@ -295,7 +295,7 @@ declare namespace Polymer {
      * @param slctr Selector to run on this local DOM scope
      * @returns Element found by the selector, or null if not found.
      */
-    $$(slctr: string): Element|null;
+    $$(slctr: string): _Element|null;
 
     /**
      * Force this element to distribute its children to its local dom.
@@ -405,7 +405,7 @@ declare namespace Polymer {
      * @param node The element to be checked.
      * @returns true if node is in this element's local DOM tree.
      */
-    isLocalDescendant(node: Element): boolean;
+    isLocalDescendant(node: _Element): boolean;
 
     /**
      * No-op for backwards compatibility. This should now be handled by
@@ -503,7 +503,7 @@ declare namespace Polymer {
      *    instance.
      * @returns Newly created and configured element.
      */
-    create(tag: string, props?: object|null): Element;
+    create(tag: string, props?: object|null): _Element;
 
     /**
      * Convenience method for importing an HTML document imperatively.
@@ -532,7 +532,7 @@ declare namespace Polymer {
      * @param node Element to test the selector against.
      * @returns Whether the element matches the selector.
      */
-    elementMatches(selector: string, node?: Element): boolean;
+    elementMatches(selector: string, node?: _Element): boolean;
 
     /**
      * Toggles an HTML attribute on or off.
@@ -542,7 +542,7 @@ declare namespace Polymer {
      *    When unspecified, the state of the attribute will be reversed.
      * @param node Node to target.  Defaults to `this`.
      */
-    toggleAttribute(name: string, bool?: boolean, node?: Element|null): void;
+    toggleAttribute(name: string, bool?: boolean, node?: _Element|null): void;
 
     /**
      * Toggles a CSS class on or off.
@@ -552,7 +552,7 @@ declare namespace Polymer {
      *    When unspecified, the state of the class will be reversed.
      * @param node Node to target.  Defaults to `this`.
      */
-    toggleClass(name: string, bool?: boolean, node?: Element|null): void;
+    toggleClass(name: string, bool?: boolean, node?: _Element|null): void;
 
     /**
      * Cross-platform helper for setting an element's CSS `transform` property.
@@ -561,7 +561,7 @@ declare namespace Polymer {
      * @param node Element to apply the transform to.
      * Defaults to `this`
      */
-    transform(transformText: string, node?: Element|null): void;
+    transform(transformText: string, node?: _Element|null): void;
 
     /**
      * Cross-platform helper for setting an element's CSS `translate3d`
@@ -573,7 +573,7 @@ declare namespace Polymer {
      * @param node Element to apply the transform to.
      * Defaults to `this`.
      */
-    translate3d(x: number, y: number, z: number, node?: Element|null): void;
+    translate3d(x: number, y: number, z: number, node?: _Element|null): void;
 
     /**
      * Removes an item from an array, if it exists.

diff --git a/types/lib/legacy/polymer.dom.d.ts b/types/lib/legacy/polymer.dom.d.ts
@@ -55,7 +55,7 @@ declare namespace Polymer {
      *   of this element changes
      * @returns Observer instance
      */
-    observeNodes(callback: (p0: Element, p1: {target: Element, addedNodes: Element[], removedNodes: Element[]}) => void): Polymer.FlattenedNodesObserver;
+    observeNodes(callback: (p0: _Element, p1: {target: _Element, addedNodes: _Element[], removedNodes: _Element[]}) => void): Polymer.FlattenedNodesObserver;
 
     /**
      * Disconnects an observer previously created via `observeNodes`
@@ -137,8 +137,8 @@ declare namespace Polymer {
     replaceChild(oldChild: Node, newChild: Node): Node;
     setAttribute(name: string, value: string): void;
     removeAttribute(name: string): void;
-    querySelector(selector: string): Element|null;
-    querySelectorAll(selector: string): NodeListOf<Element>;
+    querySelector(selector: string): _Element|null;
+    querySelectorAll(selector: string): NodeListOf<_Element>;
   }
 
 

diff --git a/types/lib/mixins/element-mixin.d.ts b/types/lib/mixins/element-mixin.d.ts
@@ -138,7 +138,7 @@ declare namespace Polymer {
     rootPath: string;
     importPath: string;
     root: StampedTemplate|HTMLElement|ShadowRoot|null;
-    $: {[key: string]: Element};
+    $: {[key: string]: _Element};
 
     /**
      * Stamps the element template.

diff --git a/types/lib/mixins/properties-changed.d.ts b/types/lib/mixins/properties-changed.d.ts
@@ -257,7 +257,7 @@ declare namespace Polymer {
      * @param value Value to serialize.
      * @param attribute Attribute name to serialize to.
      */
-    _valueToNodeAttribute(node: Element|null, value: any, attribute: string): void;
+    _valueToNodeAttribute(node: _Element|null, value: any, attribute: string): void;
 
     /**
      * Converts a typed JavaScript value to a string.

diff --git a/types/lib/mixins/property-effects.d.ts b/types/lib/mixins/property-effects.d.ts
@@ -96,7 +96,7 @@ declare namespace Polymer {
      * @returns `true` if the visited node added node-specific
      *   metadata to `nodeInfo`
      */
-    _parseTemplateNodeAttribute(node: Element|null, templateInfo: TemplateInfo|null, nodeInfo: NodeInfo|null, name: string, value: string): boolean;
+    _parseTemplateNodeAttribute(node: _Element|null, templateInfo: TemplateInfo|null, nodeInfo: NodeInfo|null, name: string, value: string): boolean;
 
     /**
      * Ensures an accessor exists for the specified property, and adds

diff --git a/types/lib/mixins/template-stamp.d.ts b/types/lib/mixins/template-stamp.d.ts
@@ -164,7 +164,7 @@ declare namespace Polymer {
      * @returns `true` if the visited node added node-specific
      *   metadata to `nodeInfo`
      */
-    _parseTemplateNodeAttributes(node: Element|null, templateInfo: TemplateInfo|null, nodeInfo: NodeInfo|null): boolean;
+    _parseTemplateNodeAttributes(node: _Element|null, templateInfo: TemplateInfo|null, nodeInfo: NodeInfo|null): boolean;
 
     /**
      * Parses a single template node attribute and adds node metadata to
@@ -181,7 +181,7 @@ declare namespace Polymer {
      * @returns `true` if the visited node added node-specific
      *   metadata to `nodeInfo`
      */
-    _parseTemplateNodeAttribute(node: Element|null, templateInfo: TemplateInfo, nodeInfo: NodeInfo, name: string, value: string): boolean;
+    _parseTemplateNodeAttribute(node: _Element|null, templateInfo: TemplateInfo, nodeInfo: NodeInfo, name: string, value: string): boolean;
 
     /**
      * Returns the `content` document fragment for a given template.

diff --git a/types/lib/utils/gestures.d.ts b/types/lib/utils/gestures.d.ts
@@ -34,7 +34,7 @@ declare namespace Polymer {
      * @returns Returns the deepest shadowRoot inclusive element
      * found at the screen position given.
      */
-    function deepTargetFind(x: number, y: number): Element|null;
+    function deepTargetFind(x: number, y: number): _Element|null;
 
 
     /**
@@ -66,7 +66,7 @@ declare namespace Polymer {
      * This value is checked on first move, thus it should be called prior to
      * adding event listeners.
      */
-    function setTouchAction(node: Element, value: string): void;
+    function setTouchAction(node: _Element, value: string): void;
 
 
     /**