XDOMPATH

Library for query DOM nodes similar to XPATH language with new features (ShadowDOM support)

Purpose of creating

XPATH language is oriented only on clear XML document model, but real DOM model now differs from XML because of ShadowDOM technology. XDomPath is new extended language which can handle ShadowDOM and allows to use DOM with ShadowDOM as XML language.

API

1. Import library into your file:

import{XDomPath}from'@telenko/xdompath';

2. Create a xdompath instance by using query as argument

constallDivsPath=newXDomPath('.//div');

3. Select a scope to query for and run XDomPath:

constdivsArr=allDivsPath.perform(document.body);

Extended XML model for DOM with ShadowDOM:

XDomPath is trying to treat DOM with ShadowDOM as XML model. To achieve that DOM model XDomPath parses in such way:

1. shadowRoot elements are parsed as always first children of host element
2. child nodes of shadowRoot are parsed as direct children of shadowRoot element
3. slotted elements are parsed as direct children of host element

Examples

//setup DOMconstcontainer=document.createElement('div');container.innerHTML=` <div id='with-shadow'></div> <span>some text</span> <div> <p class='bold_paragraph'>another text</p> </div>`;constdivWithShadow=container.children[0];divWithShadow.attachShadow({mode: "open"});divWithShadow.shadowRoot.innerHTML=` <p class='bold_paragraph'>text inside shadow</p> <input type='text'/> <div>some container inside shadow</div> <p>text</p>`;

1. Deep querying through Light/Shadow DOM

//let's queryconstqueryDivs=newXDomPath('.//div');constallDivs=queryDivs.perform(container);console.log(allDivs.length);//3constdivsInsideShadow=newXDomPath('.//shadow()//div');constshadowDivs=queryDivs.perform(container);console.log(shadowDivs.length);//1constparticularText=newXDomPath('.//text()[.="text inside shadow"]');consttexts=particularText.perform(container);console.log(texts.length);//1

2. Querying by class existence

constwithClassQuery=newXDomPath('.//p[class("bold_paragraph")]');constpsWithClass=particularText.perform(container);console.log(psWithClass.length);//2

3. Querying focusable elements

constwithClassQuery=newXDomPath('.//focusable()');constpsWithClass=particularText.perform(container);console.log(psWithClass.length);//1

4. Using regular XPATH axes

constwithClassQuery=newXDomPath('.//p[class("bold_paragraph")]/following-subling::input');constpsWithClass=particularText.perform(container);console.log(psWithClass.length);//1

Supported features

1. All XPATH axes
2. Function list:

• text()
• position()
• last()
• not()
• name() -- planned, but not supported for now
• id() -- planned, but not supported for now
• string()
• substring()
• substring-after()
• substring-before()
• string-length()
• count()
• concat()
• normalize-space()
• starts-with()
• contains()
• translate() -- planned, but not supported for now
• ceiling()
• floor()
• round()
• sum() -- planned, but not supported for now

new XDomPath functions:

• shadow() -- returns nodes which are instances of ShadowRoot
• class() -- receives string and returns true if node has class
• focusable() -- returns nodes which are focusable HTML elements

Limitations

1. Mathematical operations (except of comparison operators '=' '<' '>' '<=' '>=')
2. Some particular functions (from item above)
3. Union operator | (plan to support in future)
4. 'or' 'and' operators inside filters
5. '( )' group operators inside of filters:

newXDomPath('(.//div)[0]');//will worknewXDomPath('.//div[(position() < 3)]');//won't work

6. NodeList -> String type conversion for now works by different algorithm:

list[#text, #text, #text]->list[0].textContent;//only 1st item's textContent

Dist folder

Dist folder contains of 2 compiled js files:

• xdompath.min.js - compiled version of XDomPath
• xdompath.global.min.js - compiled version, but auto-pushed to global window scope as

window.XDomPath

Current issues

1. '..' parent axis working not properly for now. For now alias '/parent::' recommended to use instead

Plans

1. Cover more XPATH features
2. Introduce new method:

XDomPath.defineFunction(...);

to make possible extend base set of functions with custom ones