Skip to content

Latest commit

 

History

History
245 lines (174 loc) · 17.2 KB

lazy-custom-elements.md

File metadata and controls

245 lines (174 loc) · 17.2 KB
Raw

Classes

LazyCustomElementRegistry

The LazyCustomElementRegistry class is a custom element registry for defining and upgrading custom elements in a lazy manner.

Constants

lazyCustomElements : LazyCustomElementRegistry

A shared instance of LazyCustomElementRegistry


LazyCustomElementRegistry

The LazyCustomElementRegistry class is a custom element registry for defining and upgrading custom elements in a lazy manner.


new LazyCustomElementRegistry()

Creates an instance of LazyCustomElementRegistry.


lazyCustomElementRegistry.define(name, constructor, [options]) ⇒ LazyCustomElementRegistry

Equivalent of customElements.define() but supporting async definition and additional features. Define a custom element or custom built-in element, potentially in a lazy way, by passing an async callback that resolve to the Class

Returns: LazyCustomElementRegistry - return itself to allow for chain calls

Param Type Default Description
name string The name of the custom element being defined, or a partial name ending with a dash in case of late definition of custom built-in elements classes from a mixin, see options.extends description.
constructor function The constructor function or class for the custom element being defined, or an async function that will resolve to the constructor. For
[options] object {} An optional object containing configuration options for the custom element being defined. It may override some of the global options.
[options.extends] string, Array the tagName of the built-in element to be extended. It allows to specify an array of names or the string '*' supporting the late definition of the class from a mixin in the form: const ClassName = (Base) => class extends Base {}. In that case the element name needs to be defined in a partial form with a trailing dash like 'acme-my-element-'. The final name of the elements will be completed adding the built-in element name that are going to be extended, like: 'acme-my-element-button', 'acme-my-element-a' and so on.
[options.selector] string an alternative selector to identify custom elements in the dom in order to observe them for lazy defining and lazy loading. By default it will use the component name or a data attribute selector [is] for custom built-in elements
[options.autodefineAttribute] string "data-autodefine" attribute name (usually a data-attribute) to control the autodefinition behavior on the defined custom elements. Valid attribute values are 'true' (will be defined as soon as it is intercepted in the DOM), 'lazy' or an alternative value defined in options.lazyValue (will be defined when one element of this type intercepts a defined area around the viewport) or 'false' (will not be defined automatically, it will require an upgrade call to force the definition)
[options.lazyValue] string "lazy" value used to define the lazy behavior (both for autodefine and autoload features)
[options.autodefineRoot] Document, HTMLElement document root used for the autodefine IntersectionObserver
[options.autodefineRootMargin] string "100% 0px 100% 0px" margin used for the autodefine IntersectionObserver. By default it has a 100% height margin both above and below the viewport
[options.autodefineThreshold] number 0 threshold used for the autodefine IntersectionObserver
[options.autodefineDefaultValue] string "lazy" the default value for the autodefine attribute
[options.autoloadRoot] Document, HTMLElement document root used for the autoload IntersectionObserver
[options.autoloadRootMargin] string "50% 0px 50% 0px" margin used for the autoload IntersectionObserver. By default it has a 50% height margin both above and below the viewport
[options.autoloadThreshold] number 0 threshold used for the autodefine IntersectionObserver
[options.autoloadAttribute] string "data-autoload" attribute name (usually a data-attribute) to control the autoloading behavior on the defined custom elements. Valid attribute values are 'true' (will call the load method as soon as it is intercepted in the DOM), 'lazy', or an alternative value defined in options.lazyValue (will call the load method when the element is intercepted in a defined area around the viewport). Any other value will be ignored. Differently from the autodefine, elements that want to subscribe to the autoloading feature needs to have this attribute set.
[options.loadMethod] string "load" Name of the method to be called when the load is triggered
[options.firstConnectedCallbackMethod] string, boolean "firstConnectedCallback" if the custom element class contains this method, it will be called only the first time the elements are connected to the document instead of the connectedCallback() method, which instead will be called (if available) on every reconnection after the first one. An empty string or a falsy value can be passed to disable the feature when the class contains such a method but you don't want to subscribe to this automated behavior.


lazyCustomElementRegistry.get(name) ⇒ Promise.<(function()|undefined)>

Async version of CustomElementRegistry.get method. Retrieve a previously defined constructor for a given custom element name. It resolves late definitions made from a mixin in the form: const ClassName = (Base) => class extends Base {}. It also implements (through subclassing) the logic to deal with a firstConnectedCallback() method when the feature is enabled and the method is available in the defined constructor.

Returns: Promise.<(function()|undefined)> - resolves to a previously defined constructor or to undefined

Param Type Description
name string the custom element or custom built-in element name associated to the constructor to retrieve


lazyCustomElementRegistry.upgrade(root)

Async version of CustomElementRegistry.upgrade method. First it resolves all the lazy defined elements, then proceed to upgrade them.

Param Type Description
root Element the element to be upgraded, together with its descendants


lazyCustomElementRegistry.whenDefined(name) ⇒ Promise

Exact same feature as CustomElementRegistry.whenDefined.

Returns: Promise - resolves when the custom element constructor has been defined

Param Type Description
name string a custom element or custom built-in element name


lazyCustomElementRegistry.upgradeElement(element)

Same feature provided by upgrade but without forcing the definition of lazy defined descendants.

Param Type Description
element Element the element to be upgraded


lazyCustomElementRegistry.upgradeElements(elements)

Same feature provided by upgrade but for a list of elements and without forcing the definition of lazy defined descendants.

Param Type Description
elements Array, NodeList the elements to be upgraded


lazyCustomElementRegistry.querySelector(node, selectors) ⇒ Promise.<?Element>

Async equivalent of node.querySelector() followed by forcing a definition of the eventually lazy defined custom element and an upgrade of the found element.

Returns: Promise.<?Element> - returns a promise that resolves with the found element or null

Param Type Description
node Document, Element, ShadowRoot the document or node to be queried
selectors string a string containing one or more comma-separated selectors to match


lazyCustomElementRegistry.querySelectorAll(node, selectors) ⇒ Promise.<?NodeList>

Async equivalent of node.querySelectorAll() followed by forcing a definition of the eventually lazy defined custom elements and an upgrade of the found elements.

Returns: Promise.<?NodeList> - returns a promise that resolves with the found elements NodeList or null in case the node is not an instance of Document or Element to be queried

Param Type Description
node Document, Element, ShadowRoot the document or node to be queried
selectors string a string containing one or more comma-separated selectors to match


lazyCustomElementRegistry.createElement(tagName, [options]) ⇒ Element

It works exactly like document.createElement with a single additional feature to solve a weird thing. When the standard document.createElement is used to create a custom built-in element (passing an options object as a second parameter, with the "is" property filled), it set the is attribute in a way that is not properly queryable with the usual methods. Let's say you do something like:

class MyCustomParagraph extends HTMLParagraphElement {}
customElements.define('my-custom-paragraph', MyCustomParagraph, {extends: 'p'});
const p = document.createElement('p', {is: 'my-custom-paragraph});
console.log(p.matches('[is="my-custom-paragraph"]'));
// unexpectedly it prints false
// same if you attach the element in the dom and try to query it by "is" attribute, you will get no results

So in those cases, this method forces a setAttribute call with the proper values that allows the element to be queryable as expected.

Returns: Element - the created Element

Param Type Description
tagName string the tagName of the Element to be created
[options] undefined, object An optional object eventually containing the property is
[options.is] string The tagName of a custom built-in element


lazyCustomElementRegistry.setOptions(options)

Sets / overwrites config options

Param Type Default Description
options object An object containing configuration options
[options.autodefineAttribute] string "data-autodefine" attribute name (usually a data-attribute) to control the autodefinition behavior on the defined custom elements. Valid attribute values are 'true' (will be defined as soon as it is intercepted in the DOM), 'lazy' or an alternative value defined in options.lazyValue (will be defined when one element of this type intercepts a defined area around the viewport) or 'false' (will not be defined automatically, it will require an upgrade call to force the definition)
[options.lazyValue] string "lazy" value used to define the lazy behavior (both for autodefine and autoload features)
[options.autodefineRoot] Document, HTMLElement document root used for the autodefine IntersectionObserver
[options.autodefineRootMargin] string "100% 0px 100% 0px" margin used for the autodefine IntersectionObserver. By default it has a 100% height margin both above and below the viewport
[options.autodefineThreshold] number 0 threshold used for the autodefine IntersectionObserver
[options.autodefineDefaultValue] string "lazy" the default value for the autodefine attribute
[options.autoloadRoot] Document, HTMLElement document root used for the autoload IntersectionObserver
[options.autoloadRootMargin] string "50% 0px 50% 0px" margin used for the autoload IntersectionObserver. By default it has a 50% height margin both above and below the viewport
[options.autoloadThreshold] number 0 threshold used for the autodefine IntersectionObserver
[options.autoloadAttribute] string "data-autoload" attribute name (usually a data-attribute) to control the autoloading behavior on the defined custom elements. Valid attribute values are 'true' (will call the load method as soon as it is intercepted in the DOM), 'lazy', or an alternative value defined in options.lazyValue (will call the load method when the element is intercepted in a defined area around the viewport). Any other value will be ignored. Differently from the autodefine, elements that want to subscribe to the autoloading feature needs to have this attribute set.
[options.loadMethod] string "load" Name of the method to be called when the load is triggered
[options.firstConnectedCallbackMethod] string, boolean "firstConnectedCallback" if the custom element class contains this method, it will be called only the first time the elements are connected to the document instead of the connectedCallback() method, which instead will be called (if available) on every reconnection after the first one. An empty string or a falsy value can be passed to disable the feature when the class contains such a method but you don't want to subscribe to this automated behavior.


lazyCustomElementRegistry.getOptions() ⇒ object

returns a copy of an the configuration options, to avoid accidental modification outside of the registry's scope.

Returns: object - a copy of the configuration options of the options object.
See: setOptions for the full list of the options.


lazyCustomElementRegistry.getDefaultOptions() ⇒ object

returns a copy of an the default configuration options, to avoid accidental modification.

Returns: object - a copy of the default configuration options of the options object.
See: setOptions for the full list of the options.


lazyCustomElements : LazyCustomElementRegistry

A shared instance of LazyCustomElementRegistry