ApiChain and CssChain JS.

HTML template/slot and DOM manipulation library

Collection API inherits the element API and Array.

git GitHub | Demo: css-chain | tests project

CssChain.js

html elements methods

CssChain searches HTML by css and returns an Array inherited object which has all methods and properties of its elements. When method is called, each element would invoke this method and then same CssChain object is returned.

import $ from 'https://unpkg.com/css-chain@1/CssChain.js'
$( '*[title]', rootEL ).addEventListener( 'click', ev=> alert(ev.target.title) );

^^ adds event listener to all selected elements in rootEl DOM tree

chained calls	HTMLElement API

    CssChain( 'a' )
        .addEventListener( 'mouseover' , ev=> alert(ev.target.classList.add('hovered') ) )
        .addEventListener( 'mouseleave', ev=> alert(ev.target.classList.remove('hovered') ) )
        .on( 'focus'     , ev=> alert(ev.target.classList.add('focused') ) )
        .on( 'mouseleave', ev=> alert(ev.target.classList.remove('focused') ) )

^^ adds multiple event handlers in chainable dot notation.

Typescript

import CssChain from 'css-chain' code has typings enabled by default. The chain type is a mixin of HTMLElementMixin and array of this mixin. To add the type checking for custom element(s) CssChain accept generics parameter and needs at least once initialisation by 3rd parameter as array of either custom element tags or classes.

import {CssChain as $ } from 'css-chain';

class DemoElement {  b:string; setB(_b: string) { this.b = _b; } }
customElements.define('demo-element', DemoElement );

const $X = $<DemoElement>('demo-element', el, ['demo-element']);

expect($X.b).to.equal('initial');
$X.setB('1');

CssChain initialization

CssChain(css) return mixin of HTMLElementMixin and array
CssChain(css,from:Node|Node[]|CssChain) css selector to be applied on node(s)
CssChain(css,from, protoArr) -||- with prototype(s) for members and methods of CssChain, needed to support methods of web component

To avoid passing the prototype each time, it could be initialized in module global scope:

import {CssChain as $ } from 'css-chain';
// import or declare DemoElement
$([],[],[DemoElement]);
// now all methods and members of DemoElement available in CssChain everywhere.

special methods

forEach() - same as Array.forEach returns CssChain
map() - same as Array.map returns new CssChain with elements from callback
push(...arr) - same as Array.push returns appended CssChain
querySelector(css) - selects 1st element, returns CssChain
querySelectorAll(css) - selects all children matching css , returns CssChain
$ - alias to querySelectorAll()
attr(name) (alias for getAttribute) returns 1st element attribute value or undefined for empty collection
attr(name, val|cb(el,i,arr)) (alias for setAttribute) sets elements attribute, returns CssChain
attr(name, val|cb(el,i,arrCss,arrThis),css) (alias for setAttribute) sets css-defined sub-tree elements attribute, returns CssChain
prop(name) returns 1st element property value or undefined for empty collection
prop(name, val|cb(el,i,arr)) sets elements attribute, returns CssChain
prop(name, val|cb(el,i,arrCss,arrThis), css) sets css-defined sub-tree elements attribute, returns CssChain
parent() - set of immediate parents of current collection, duplications removed
parent(css) - set of parents of current set which matches the selector, duplications removed
on(eventName, cb) - alias to addEventListener
remove(eventName, cb) - alias to removeEventListener
remove() - delete all nodes, returns empty CssChain
erase() - removes content of collection nodes, collection nodes remain
txt() - returns text of whole collection
txt( val | cb(el,i,arr)) - sets text for each element from val or callback
txt( val | cb(el,i,arrCss,arrThis), css ) sets text for children elements defined by css, returns original collection
html() - returns concatenated innerHTML of collection
html( cb(el,i,arr) ) - sets innerHTML of each collection element
html(htmlText) - sets innerHTML of each collection element
html(strArr|NodeList) - array duplicated within each collection element
html( val, css ) sets html for children elements defined by css. val type is one of above. Returns original collection
cloneNode(deep) - returns collection of cloned elements of current one by Node.cloneNode(deep)
clone() - clone nodes(deep) or objects(shallow). Returns cloned collection
clone(doc) - clone nodes to be inserted into document using Document.importNode()
clone( count, cb( clonedNode, index ) ) when callback result is a string or node it is used as return value
clone( arr ) alias of clone(arr.length)
clone( arr, cb( clonedNode, dataItem, index, arr ) ) call callback after clone
append( html ),append( html[] ), append( node[] ) append HTML text or nodes

Light DOM

Shadow DOM and its twin Light DOM allows to use template and work with dynamic content withing template. Both often represent the content of web component as convenient way to generate DOM subtree by JavaScript.

In the light DOM as opposite to Shadow DOM the render root is part of usual DOM without engaging the shadowRoot. There the template clone would take a render root DOM subtree payload as the source for its slot assignment. Once slots are populated into this clone, it would replace the render root content.

Of course such benefits of shadow DOM as template reuse and CSS encapsulation are lost in light DOM. But the modular development with templates, HTML5 standard dynamic content use convention and API are still around.

global CSS

is available for styling the light DOM components, which could be advantage in some environments where css encapsulation of shadow DOM in web components prevents usual css styling.

Light DOM API

template() would render the current node as a template with immediate children with slot='xxx' as assignedNodes payload for <slot name='xxx'>. There is no default slot in such case as the inner DOM serves the default content.
template(css), typically template('template') would extract the template defined by selector, clone it with assigned slots from remaining children
template(node) the children are used as slot content within node clone which is set as a child

slots

<slot name='xxx'></slot> is an HTML tag, a marker where dynamic content would be placed. It works with shadow and light DOM in same manner.

When used with template() or by shadow DOM, dynamic content is taken from DOM subtree marked by slot='xxx' attribute.

Otherwise slot content could be manipulated by JS API:

slots() - returns all slots
slots('') - returns slot without name
slots(',name1,name2...') - returns named slots. Blank name defines unnamed(default) slot
slots(name, val | cb(el,i,arr) ) assigns slot content, alias to HTMLSlotElement.assign(nodes) when cb is defined slots content is set by html(cb)
slots().innerText,slots().innerHTML, slots().txt(), slots().html() sets slotted content

html elements properties

When property is assigned to collection, this property would be set for all elements in collection. The property get would return property from 1st element.

    import { CssChain as $ } from '../src/CssChain.js';
    $( 'input' ).value = 'not defined'; // all INPUT elements would have new value set
    v = $( 'input' ).prop( value,'not defined' ); // same as ^^
    let  v = $( 'input' ).value; // variable would receive the 1st INPUT element value
    v = $( 'input' ).prop( value ); // same as ^^

ApiChain.js

Array of raw objects

    $([ {a:1},{a:2} ]).a=1;    // all arr elements property `a` set to 1
    v = $([ {a:1},{a:2} ]).a;  // 1st element property `a` is returned, i.e. 1
    $( [ { a:1,f(v){ this.a=v} }, { b:2,f(v){ this.b=v}} ])
        .f(3); // method called on each element, result [{a:3},{b:3}]

Array of class objects

Could be initiated in same fashion as raw objects. But for performance better to provide the reference object as a second parameter:

    class A{ f(){} }
    const x = new A(), y = new A();
    $( [x,y], A ).f()

cssChain - initiated by css selector from HTMLElement API

Registered interfaces are taken from window object by window.HTML*Element pattern. To use API from custom elements, add those in array of last

Api selected either from elements in collection or from window.HTML*Element.

import {CssChain as $} from 'api-chain/CssChain.js';
$('input').value=''; // set all INPUT elements on page value to blank string
$('input').forEach( (el,i) => el.value=i ) // all array methods available
$('[type="checkbox"]')
  .prop( 'checked', false ) // set property and return same CssChain 
  .addEventListener('click' ,function(){  }) // methods are called for each element
  .addEventListener('change',function(){ this.checked; }) // and could be chained
  .on( 'hover', ()=>showTooltip() ) // 'on' is alias to `addEventListener`
  
const firstFormUrl = $('form').action; // returns property valuye of 1st element in collection.
const firstLinkUrl = $('a').href; // returns property valuye of 1st element in collection.
$('a').prop('href'); // same as above
$('a').attr('href'); // same as getAttribute() for 1st element in collection

optimization

API simulation is expensive when done on each occasion. Pre-generated API wrappers could be added on app load time. CssChain on module load applied the whole set of window.HTML*Element.

In the call of ApiChain the last parameter is an array of prototype objects. The classes listed in this array would be stored in global map and generated API would be reused next time same class is listed within last parameter.

class A{ f1(){} } class B{ f2(){} }
const a = new A, b = new A;
ApiChain( [a,b] ).f1().f2() // would generate API on each call
ApiChain( [], [A,B] ) // would generate from prototypes array on 1st call
ApiChain( [a,b] ).f1().f2() // would reuse API generated in previous call

Samples of use

PokéAPI Explorer:

sashafirsov/css-chain