@browserkids/dom

v0.6.0

Published

3 years ago

Non-transpiled ES6+ DOM helper functions.

Downloads

0High
0Medium
0Low

mzdr

dom functions

Installation

Using a CDN

Fastest way to get going. See for yourself:

<script type="module">
import { isElementInViewport } from 'https://unpkg.com/@browserkids/dom';

console.log(isElementInViewport(document.body))
</script>

Self hosted

Semi-fast way. Download the files and upload them to your server. Just make sure your import path is correct.

import { isElementInViewport } from './assets/@browserkids/dom/index.js';

Using a bundler

Semi-fast way as well. Just install it via npm.

npm install -S @browserkids/dom

Import the functions where you need them.

import { isElementInViewport } from '@browserkids/dom';

Single import

Just want to import a single function?

<script type="module">
import isElementInViewport from 'https://unpkg.com/@browserkids/dom/isElementInViewport';

console.log(isElementInViewport(document.body))
</script>

:warning: Some functions depend on other @browserkids/dom functions. See API chapter for details.

<script type="module">
import findAttributes from 'https://unpkg.com/@browserkids/dom/findAttributes';
import findReferences from 'https://unpkg.com/@browserkids/dom/findReferences';

// Provide necessary functions via settings object.
console.log(findReferences(document.body, { findAttributes }))
</script>

Browser support

Almost every function uses at least one feature of ECMAScript 9 or above, but no ESNext features — promised. So support should be fine for “evergreen” browsers at the time of writing. This means that Internet Explorer is out of the game.

As this library is not transpiled nor ever will be you should use polyfills in case you need to support a specific browser version.

API

createShadowRoot($el, template = '', settings = {})
Creates a Shadow DOM for this element and uses the given template as content.

By default this creates an open Shadow DOM. A very simple example on how to use this would be:

<my-custom-element>rock!</my-custom-element>
   
<script type="module">
  import { createShadowRoot } from 'https://unpkg.com/@browserkids/dom';
   
  customElements.define('my-custom-element', class MyCustomElement extends HTMLElement {
    constructor() {
      super();
           
      createShadowRoot(this, `
        <style>
          :host::before {
            content: 'My scoped styles…';
          }
        </style>
           
        <slot></slot>
      `);
    }
  });
</script>

dispatch($el, name, detail, settings = {})
Triggers a custom event with the given data.
This function has some sensible defaults like bubbling enabled or no trespassing of the event between the boundary of shadow and regular DOM.

findAttributes($el, name))
Tries to find attributes that name is matching a given regular expression.

<main #container class="random-class">Just a random element.</main>
  
<script type="module">
  import { findAttributes } from 'https://unpkg.com/@browserkids/dom';
  
  // [{ name: '#container', value: '' }]
  console.log(findAttributes(document.querySelector('main'), /^#.+/));
</script>

findReferences($el, settings = {})
Finds all elements within a given element that have #referenceId (by default) attributes.
:warning: If you single-import this function, make sure to provide a findAttributes() function.
```
<body>
  <header #header></header>
  <main #content>
    <h1 #headline></h1>
  </main>
  <footer #footer></footer>
</body>
   
<script type="module">
  import { findReferences } from 'https://unpkg.com/@browserkids/dom';
   
  // { header: header, headline: h1, content: main, footer: footer }
  console.log(findReferences(document.body));
</script>
```
Available settings:
- pattern (default: /^#(?<id>.+)/), adjust the RegEx pattern for finding references.
- cleanUp (default: true), remove attributes after finding reference.
- findAttributes, function for finding attributes. This is only mandatory if you single-import this function.
isElementInViewport($el, settings = {})
Returns true if the given element is within the boundaries of the given viewport coordinates or at least the amount specified.
You may adjust the following settings:
- amount, specify minimum amount of overlapping/intersection between target element and viewport.
- viewport, provide a custom viewport bounding rectangle. Default is window rectangle.
bindEventListeners($el, scope = $el, settings = {})
Finds all elements that have @event[.modifier]="function" (by default) attributes and automatically registers the event listeners to the elements.
:warning: If you single-import this function, make sure to provide a findAttributes() function.
```
<main @click="onClick">Just a random element.</main>
   
<script type="module">
  import { bindEventListeners } from 'https://unpkg.com/@browserkids/dom';
   
  bindEventListeners(document.body, {
    onClick() {
      console.log('I just got clicked.');
    }
  });
</script>
```
There are a few modifiers available:
- prevent calls e.preventDefault() before running the event listener.
- self, calls only when event.target === event.currentTarget.
- away, calls only when the event.target is not a child of event listener element.
- once, calls the event listener only once.
- window, attaches the event listener to the window object.
- document, attaches the event listener to the document object.
Available settings:
- pattern (default: /^@(?<event>[^.]+).?(?<modifier>.+)?/), adjust the RegEx pattern for finding event hooks.
- cleanUp (default: true), remove attributes after finding reference.
- findAttributes, function for finding attributes. This is only mandatory if you single-import this function.

upgrade($el, template)

All-in-one function that will run createShadowRoot, bindEventListeners, findReferences.

:warning: If you single-import this function, make sure all necessary functions are known to the global scope.

<my-custom-element></my-custom-element>
  
<script type="module">
  import { upgrade } from 'https://unpkg.com/@browserkids/dom';
   
  customElements.define('my-custom-element', class MyCustomElement extends HTMLElement {
    constructor() {
      super();
           
      upgrade(this, '<button @click="onClick" #button>Hit me</button>');

      console.log(this.$refs);
    }

    onClick() {
      console.log('I was clicked.');
    }
  });
</script>

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme