Generate “x-element.d.ts” from JSDoc comments.

Previously, the “x-element.d.ts” file was hand-curated, which was prone
to falling out of date.

Because the TypeScript team manages JSDoc, it’s fairly straightforward
to properly “type” your JS with JSDoc and output declarations which can
be used by folks writing TypeScript — all of that without needing to
actually author TypeScript ourselves.†

Additionally, tools like JSR will build basic documentation for
libraries which author JSDoc comments, so some wins there.

Finally, to ensure best practices for our JSDocs, we enable some
recommended rules from the eslint plugin.

† One goal of “x-element” is to be _highly_ portable, it’s why no
  dependencies exist and why the “x-element.js” file can be used
  _verbatim_ without a build step.

.github/workflows/test.yaml

@@ -12,6 +12,8 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
       - run: npm ci
       - run: npm run lint
+      - run: npm run type
+      - run: git diff --exit-code
       - run: npm start &
       - run: sleep 2
       - run: npm test

CHANGELOG.md

@@ -13,6 +13,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - The `map` function now works with properties / attributes bound across template contexts (#179).
+- The `x-element.d.ts` file now reflects the actual interface. Previously, it
+  has some issues (e.g., improper module export).
+
+### Changed
+
+- The `x-element.js` file is now “typed” via JSDoc. The validity of the JSDoc
+  comments are linted alongside the rest of the code and the annotations there
+  are exported into a generated `x-element.d.ts` file. Previously, that file was
+  hand-curated.
 
 ## [1.0.0] - 2024-02-29
 

deno.json

@@ -1,5 +1,18 @@
 {
   "name": "@netflix/x-element",
   "version": "1.0.0",
-  "exports": "./x-element.js"
+  "exports": {
+    "./x-element.js":  "./x-element.js",
+    "./x-element.d.ts": "./x-element.d.ts",
+    "./etc/ready.js": "./etc/ready.js",
+    "./etc/ready.d.ts": "./etc/ready.d.ts"
+  },
+  "include": [
+    "./x-element.js",
+    "./x-element.d.ts",
+    "./x-element.d.ts.map",
+    "./etc/ready.js",
+    "./etc/ready.d.ts",
+    "./etc/ready.d.ts.map"
+  ]
 }

eslint.config.js

@@ -1,7 +1,9 @@
 import globals from 'globals';
+import jsdoc from 'eslint-plugin-jsdoc';
 import NetflixCommon from '@netflix/eslint-config';
 
 export default [
+  jsdoc.configs['flat/recommended'],
   {
     ...NetflixCommon,
     files: ['**/*.js'],
@@ -12,6 +14,15 @@ export default [
       'demo/react/*',
     ],
   },
+  {
+    files: ['x-element.js', 'etc/ready.js'],
+    plugins: { jsdoc },
+    rules: {
+      'jsdoc/require-param-description': 'off',
+      'jsdoc/require-property-description': 'off',
+      'jsdoc/require-returns-description': 'off',
+    },
+  },
   {
     ...NetflixCommon,
     files: ['demo/react/**/*.js'],

etc/ready.d.ts

@@ -0,0 +1,9 @@
+export default ready;
+/**
+ * Await document completeness. Will likely be replaced by built-in apis.
+ * Check out https://github.com/Netflix/x-element/issues/65 for details.
+ * @param {Document} target
+ * @returns {Promise<any>}
+ */
+declare function ready(target: Document): Promise<any>;
+//# sourceMappingURL=ready.d.ts.map

etc/ready.js

@@ -1,3 +1,9 @@
+/**
+ * Await document completeness. Will likely be replaced by built-in apis.
+ * Check out https://github.com/Netflix/x-element/issues/65 for details.
+ * @param {Document} target
+ * @returns {Promise<any>}
+ */
 const ready = target => {
   return new Promise(resolve => {
     if (target.readyState === 'complete') {