Add TS externs.

.eslintignore

@@ -36,4 +36,5 @@ packages/webcomponentsjs/src/platform/
 packages/webcomponentsjs/src/flag-parser.*
 packages/webcomponentsjs/src/unresolved.*
 packages/webcomponentsjs/custom-elements-es5-adapter.js
+packages/webcomponentsjs/webcomponents-bundle.d.ts
 packages/webcomponentsjs/webcomponents-bundle.js*

.gitignore

@@ -31,4 +31,5 @@ packages/webcomponentsjs/src/platform/
 packages/webcomponentsjs/src/flag-parser.*
 packages/webcomponentsjs/src/unresolved.*
 packages/webcomponentsjs/custom-elements-es5-adapter.js
+packages/webcomponentsjs/webcomponents-bundle.d.ts
 packages/webcomponentsjs/webcomponents-bundle.js*

.prettierignore

@@ -36,6 +36,7 @@ packages/webcomponentsjs/src/platform/
 packages/webcomponentsjs/src/flag-parser.*
 packages/webcomponentsjs/src/unresolved.*
 packages/webcomponentsjs/custom-elements-es5-adapter.js
+packages/webcomponentsjs/webcomponents-bundle.d.ts
 packages/webcomponentsjs/webcomponents-bundle.js*
 
 LICENSE

packages/custom-elements/CHANGELOG.md

@@ -5,7 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+- Add TS externs. ([#457](https://github.com/webcomponents/polyfills/pull/457))
 
 ## [1.4.3] - 2020-10-21
 

packages/custom-elements/externs/custom-elements.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright (c) 2021 The Polymer Project Authors. All rights reserved. This
+ * code may only be used under the BSD style license found at
+ * http://polymer.github.io/LICENSE.txt The complete set of authors may be found
+ * at http://polymer.github.io/AUTHORS.txt The complete set of contributors may
+ * be found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by
+ * Google as part of the polymer project is also subject to an additional IP
+ * rights grant found at http://polymer.github.io/PATENTS.txt
+ */
+
+// When building externally, this file is always assumed to be a module, but by
+// default it isn't when building internally, so we need this export statement.
+export {};
+
+declare global {
+  interface CustomElementRegistry {
+    forcePolyfill?: boolean;
+    polyfillWrapFlushCallback?(outer: (fn: () => void) => void): void;
+    noDocumentConstructionObserver?: boolean;
+    shadyDomFastWalk?: boolean;
+  }
+}

packages/custom-elements/package.json

@@ -34,5 +34,9 @@
     "webcomponents",
     "polyfill",
     "shim"
-  ]
+  ],
+  "devDependencies": {
+    "@webcomponents/html-imports": "^1.2.6",
+    "@webcomponents/shadydom": "^1.8.0"
+  }
 }

packages/custom-elements/ts_src/CustomElementInternals.ts

@@ -9,9 +9,8 @@
  * rights grant found at http://polymer.github.io/PATENTS.txt
  */
 
-import './Externs.js';
+import CustomElementRegistry from './CustomElementRegistry.js';
 import {CustomElementState as CEState} from './CustomElementState.js';
-import {CustomElementDefinition, HTMLImportElement} from './Externs.js';
 import * as Native from './Patch/Native.js';
 import * as Utilities from './Utilities.js';
 
@@ -217,7 +216,7 @@ export default class CustomElementInternals {
         element.localName === 'link' &&
         element.getAttribute('rel') === 'import'
       ) {
-        const importElem = element as HTMLImportElement;
+        const importElem = element as HTMLLinkElement;
         // The HTML Imports polyfill sets a descendant element of the link to
         // the `import` property, specifically this is *not* a Document.
         const importNode = importElem.import;
@@ -228,10 +227,7 @@ export default class CustomElementInternals {
           importNode.__CE_registry = document.__CE_registry;
         }
 
-        if (
-          importNode &&
-          (importNode as HTMLImportDocument).readyState === 'complete'
-        ) {
+        if (importNode && importNode.readyState === 'complete') {
           importNode.__CE_documentLoadHandled = true;
         } else {
           // If this link's import root is not available, its contents can't
@@ -417,7 +413,9 @@ export default class CustomElementInternals {
       return;
     }
 
-    return registry.internal_localNameToDefinition(localName);
+    return (registry as CustomElementRegistry).internal_localNameToDefinition(
+      localName
+    );
   }
 
   /**
@@ -438,7 +436,9 @@ export default class CustomElementInternals {
     // Only create custom elements if the document is associated with a
     // registry.
     if (registry && (namespace === null || namespace === NS_HTML)) {
-      const definition = registry.internal_localNameToDefinition(localName);
+      const definition = (registry as CustomElementRegistry).internal_localNameToDefinition(
+        localName
+      );
       if (definition) {
         try {
           const result = new definition.constructorFunction();
@@ -539,14 +539,24 @@ export default class CustomElementInternals {
    *
    * @see https://html.spec.whatwg.org/multipage/webappapis.html#report-the-exception
    */
-  reportTheException(error: Error) {
+  reportTheException(errorArg: Error) {
+    interface ExtendedError extends Error {
+      // Non-standard Safari properties.
+      sourceURL?: string;
+      line?: number;
+      column?: number;
+
+      // Non-standard Firefox properties.
+      fileName?: string;
+      lineNumber?: number;
+      columnNumber?: number;
+    }
+
+    const error = errorArg as ExtendedError;
     const message = error.message;
-    const filename =
-      /* Safari */ error.sourceURL || /* Firefox */ error.fileName || '';
-    const lineno =
-      /* Safari */ error.line || /* Firefox */ error.lineNumber || 0;
-    const colno =
-      /* Safari */ error.column || /* Firefox */ error.columnNumber || 0;
+    const filename = error.sourceURL || error.fileName || '';
+    const lineno = error.line || error.lineNumber || 0;
+    const colno = error.column || error.columnNumber || 0;
 
     let event: ErrorEvent | undefined = undefined;
     if (ErrorEvent.prototype.initErrorEvent === undefined) {
@@ -594,7 +604,3 @@ export default class CustomElementInternals {
     }
   }
 }
-
-declare interface HTMLImportDocument extends Node {
-  readyState: 'complete' | string;
-}

packages/custom-elements/ts_src/CustomElementRegistry.ts

@@ -13,7 +13,6 @@ import {AlreadyConstructedMarkerType} from './AlreadyConstructedMarker.js';
 import CustomElementInternals from './CustomElementInternals.js';
 import Deferred from './Deferred.js';
 import DocumentConstructionObserver from './DocumentConstructionObserver.js';
-import {Constructor, CustomElementDefinition} from './Externs.js';
 import * as Utilities from './Utilities.js';
 
 interface ElementConstructor {
@@ -35,7 +34,7 @@ export default class CustomElementRegistry {
     CustomElementDefinition
   >();
   private readonly _constructorToDefinition = new Map<
-    Constructor<HTMLElement>,
+    ElementConstructor,
     CustomElementDefinition
   >();
   private _elementDefinitionIsRunning = false;

packages/custom-elements/ts_src/Patch/HTMLElement.ts

@@ -11,8 +11,8 @@
 
 import AlreadyConstructedMarker from '../AlreadyConstructedMarker.js';
 import CustomElementInternals from '../CustomElementInternals.js';
+import CustomElementRegistry from '../CustomElementRegistry.js';
 import CEState from '../CustomElementState.js';
-import {Constructor} from '../Externs.js';
 import * as Native from './Native.js';
 
 export default function (internals: CustomElementInternals) {
@@ -21,11 +21,13 @@ export default function (internals: CustomElementInternals) {
     // emulated in ES5. Assuming the user keeps the default value of the
     // constructor's prototype's `constructor` property, this is
     // equivalent.
-    const constructor = this.constructor as Constructor<HTMLElement>;
+    const constructor = this.constructor as {new (): HTMLElement};
 
     // Always look up the definition from the global registry.
     const registry = document.__CE_registry!;
-    const definition = registry.internal_constructorToDefinition(constructor);
+    const definition = (registry as CustomElementRegistry).internal_constructorToDefinition(
+      constructor
+    );
     if (!definition) {
       throw new Error(
         'Failed to construct a custom element: ' +

packages/custom-elements/ts_src/Utilities.ts

@@ -9,8 +9,6 @@
  * rights grant found at http://polymer.github.io/PATENTS.txt
  */
 
-import {HTMLImportElement} from './Externs.js';
-
 const reservedElementNameSet = new Set<string>();
 // IE11 does not support constructing a set using an iterable.
 [
@@ -111,7 +109,7 @@ export function walkDeepDescendantElements(
       if (localName === 'link' && element.getAttribute('rel') === 'import') {
         // If this import (polyfilled or not) has its root node available,
         // walk it.
-        const importNode = (element as HTMLImportElement).import;
+        const importNode = (element as HTMLLinkElement).import;
         if (visitedImports === undefined) {
           visitedImports = new Set();
         }