From 5c62c144e2bb5aac25430264c0859b624f29b49e Mon Sep 17 00:00:00 2001 From: Manuel Martin Date: Fri, 24 Apr 2020 17:07:09 +0200 Subject: [PATCH] chore(scoped-elements): add types and refactor jsDoc --- packages/scoped-elements/index.js | 2 ++ .../src/ScopedElementsMixin.js | 24 +++++++++++++++---- packages/scoped-elements/src/transform.js | 21 ++++++++++------ packages/scoped-elements/src/types.d.ts | 3 +++ 4 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 packages/scoped-elements/src/types.d.ts diff --git a/packages/scoped-elements/index.js b/packages/scoped-elements/index.js index a215ff41..1aaf23db 100644 --- a/packages/scoped-elements/index.js +++ b/packages/scoped-elements/index.js @@ -1 +1,3 @@ +/** @typedef {import('./src/types').ScopedElementsMap} ScopedElementsMap */ + export { ScopedElementsMixin } from './src/ScopedElementsMixin.js'; diff --git a/packages/scoped-elements/src/ScopedElementsMixin.js b/packages/scoped-elements/src/ScopedElementsMixin.js index 5b3b6a09..55d5cd22 100644 --- a/packages/scoped-elements/src/ScopedElementsMixin.js +++ b/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} */ @@ -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.} scopedElements + * @param {ScopedElementsMap} scopedElements * @param {Map} templateCache * @param {Map} 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.} scopedElements + * @param {ScopedElementsMap} scopedElements * @param {Map} templateCache * @param {Map} 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} templateCache + * @param {Map} 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.'); diff --git a/packages/scoped-elements/src/transform.js b/packages/scoped-elements/src/transform.js index 44e37fe4..ed4f0cfc 100644 --- a/packages/scoped-elements/src/transform.js +++ b/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.} tags + * @param {ScopedElementsMap} scopedElements * @param {Map} templateCache * @param {Map} 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.} tags + * @param {ScopedElementsMap} scopedElements * @param {Map} templateCache * @param {Map} 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) + ); } diff --git a/packages/scoped-elements/src/types.d.ts b/packages/scoped-elements/src/types.d.ts new file mode 100644 index 00000000..36967ba9 --- /dev/null +++ b/packages/scoped-elements/src/types.d.ts @@ -0,0 +1,3 @@ +export type ScopedElementsMap = { + [key: string]: typeof HTMLElement; +}