chore(scoped-elements): add types and refactor jsDoc

packages/scoped-elements/index.js

@@ -1 +1,3 @@
+/** @typedef {import('./src/types').ScopedElementsMap} ScopedElementsMap */
+
 export { ScopedElementsMixin } from './src/ScopedElementsMixin.js';

packages/scoped-elements/src/ScopedElementsMixin.js

@@ -6,6 +6,7 @@ import { defineScopedElement, registerElement } from './registerElement.js';
 import { shadyTemplateFactory } from './shadyTemplateFactory.js';
 
 /**
+ * @typedef {import('./types').ScopedElementsMap} ScopedElementsMap
  * @typedef {import('lit-html/lib/shady-render').ShadyRenderOptions} ShadyRenderOptions
  * @typedef {function(TemplateResult, Element|DocumentFragment|ShadowRoot, ShadyRenderOptions): void} RenderFunction
  */
@@ -19,6 +20,7 @@ const templateCaches = new WeakMap();
 
 /**
  * Retrieves or creates a templateCache for a specific key
+ *
  * @param {Function} key
  * @returns {Map<TemplateStringsArray, TemplateStringsArray>}
  */
@@ -54,7 +56,7 @@ const getTagsCache = key => {
  * Transforms an array of TemplateResults or arrays into another one with resolved scoped elements
  *
  * @param {ReadonlyArray} items
- * @param {Object.<string, typeof HTMLElement>} scopedElements
+ * @param {ScopedElementsMap} scopedElements
  * @param {Map<TemplateStringsArray, TemplateStringsArray>} templateCache
  * @param {Map<string, string>} tagsCache
  * @returns {ReadonlyArray}
@@ -76,7 +78,7 @@ const transformArray = (items, scopedElements, templateCache, tagsCache) =>
  * Transforms a TemplateResult into another one with resolved scoped elements
  *
  * @param {TemplateResult} template
- * @param {Object.<string, typeof HTMLElement>} scopedElements
+ * @param {ScopedElementsMap} scopedElements
  * @param {Map<TemplateStringsArray, TemplateStringsArray>} templateCache
  * @param {Map<string, string>} tagsCache
  * @returns {TemplateResult}
@@ -89,6 +91,15 @@ const transformTemplate = (template, scopedElements, templateCache, tagsCache) =
     template.processor,
   );
 
+/**
+ * Gets an instance of the ScopedElementsTemplateFactory
+ *
+ * @param {string} scopeName
+ * @param {ScopedElementsMap} scopedElements
+ * @param {Map<TemplateStringsArray, TemplateStringsArray>} templateCache
+ * @param {Map<string, string>} tagsCache
+ * @returns {function(any): any}
+ */
 const scopedElementsTemplateFactory = (
   scopeName,
   scopedElements,
@@ -104,13 +115,16 @@ export const ScopedElementsMixin = dedupeMixin(
   superclass =>
     // eslint-disable-next-line no-shadow
     class ScopedElementsMixin extends superclass {
+      /**
+       * Obtains the scoped elements definitions map
+       *
+       * @returns {ScopedElementsMap}
+       */
       static get scopedElements() {
         return {};
       }
 
-      /**
-       * @override
-       */
+      /** @override */
       static render(template, container, options) {
         if (!options || typeof options !== 'object' || !options.scopeName) {
           throw new Error('The `scopeName` option is required.');

packages/scoped-elements/src/transform.js

@@ -1,7 +1,11 @@
 import { registerElement } from './registerElement.js';
 
 /**
- * allowed tag name chars
+ * @typedef {import('./types').ScopedElementsMap} ScopedElementsMap
+ */
+
+/**
+ * Allowed tag name chars
  *
  * @type {string}
  */
@@ -42,19 +46,19 @@ const matchAll = str => {
  * Transforms a string array into another one with resolved scoped elements and caches it for future references
  *
  * @param {TemplateStringsArray} strings
- * @param {Object.<string, typeof HTMLElement>} tags
+ * @param {ScopedElementsMap} scopedElements
  * @param {Map<TemplateStringsArray, TemplateStringsArray>} templateCache
  * @param {Map<string, string>} tagsCache
  * @returns {TemplateStringsArray}
  */
-const transformTemplate = (strings, tags, templateCache, tagsCache) => {
+const transformTemplate = (strings, scopedElements, templateCache, tagsCache) => {
   const transformedStrings = strings.map(str => {
     let acc = str;
     const matches = matchAll(str);
 
     for (let i = matches.length - 1; i >= 0; i -= 1) {
       const item = matches[i];
-      const klass = tags[item[1]];
+      const klass = scopedElements[item[1]];
       const tag = registerElement(item[1], klass, tagsCache);
       const start = item.index + item[0].length - item[1].length;
       const end = start + item[1].length;
@@ -79,11 +83,14 @@ const transformTemplate = (strings, tags, templateCache, tagsCache) => {
  *
  * @exports
  * @param {TemplateStringsArray} strings
- * @param {Object.<string, typeof HTMLElement>} tags
+ * @param {ScopedElementsMap} scopedElements
  * @param {Map<TemplateStringsArray, TemplateStringsArray>} templateCache
  * @param {Map<string, string>} tagsCache
  * @returns {TemplateStringsArray}
  */
-export function transform(strings, tags, templateCache = globalCache, tagsCache) {
-  return templateCache.get(strings) || transformTemplate(strings, tags, templateCache, tagsCache);
+export function transform(strings, scopedElements, templateCache = globalCache, tagsCache) {
+  return (
+    templateCache.get(strings) ||
+    transformTemplate(strings, scopedElements, templateCache, tagsCache)
+  );
 }

packages/scoped-elements/src/types.d.ts

@@ -0,0 +1,3 @@
+export type ScopedElementsMap = {
+    [key: string]: typeof HTMLElement;
+}