libcss-js

Parses CSS and lets you query the computed style of elements in your document tree. Uses the NetSurf browser's LibCSS, transpiled to JavaScript.

Installation

npm install libcss

Usage

Consider the following document tree:

<divid="parent"><divid="box" class="sections"><pid="a-paragraph">
Some text.
</p></div><divid="info" class="sections floaty" style="color: pink;"></div></div>

Note: libcss-js will work with any document tree, not only HTML!

varlibcss=require('libcss');varhandlers={/* see below */};libcss.init(handlers);varcss1='div { color: red; width: 70em; display: flex; }'varcss2='#box { color: green; } #parent > .floaty { float: left; }'libcss.addSheet(css1);libcss.addSheet(css2);varparStyle=libcss.getStyle('a-paragraph');varboxStyle=libcss.getStyle('box');console.log(parStyle['color']);// '#ff00ff00', formated as #aarrggbbconsole.log(boxStyle['width']);// '70em'libcss.dropSheets()parStyle=libcss.getStyle('a-paragraph');boxStyle=libcss.getStyle('box');console.log(parStyle['color']);// '#ff000000'console.log(boxStyle['width']);// 'auto'

API

libcss.init(config)

This method enables libcss-js to navigate your document tree. It must be called before queries are made.

config<object>

All members of this object must be callback functions. The identifier parameter is a string that uniquely identifies an element in your document tree.

The following example provides all the required handlers (callback functions) to libcss-js. For simplicity, we will use the element id as the identifier string, but you should use something more consistent, such as a hash or a UUID:

libcss.init({getTagName: function(identifier){// Must return a string with the tag name of the element, such as:// 'div', or 'p', or 'body'.varelement=document.getElementById(identifier);returnelement.tagName;},getAttributes: function(identifier){// Must return an array of objects in the format:// { attribute: <string>, value: <string> }// Must include all HTML attributes of the element, such as class, id, etc.varelement=document.getElementById(identifier);varattrs=[]for(letkeyinelement.attributes){if(element.attributes[key].nodeName){attrs.push({attribute: element.attributes[key].nodeName,value: element.attributes[key].nodeValue})}}returnattrs;},getSiblings: function(identifier){// Must return an array of objects that describe the siblings.// Format: { tagName: <string>, identifier: <string> }// This array must contain, in order, all of the parent's children,// including the element being queried.varelement=document.getElementById(identifier);varsibs=[];for(letsofelement.parentElement.children){sibs.push({tagName: s.tagName,identifier: s.id});}},getAncestors: function(identifier){// Must return an array of objects that describe the ancestors.// Format: { tagName: <string>, identifier: <string> }// This array must contain, in order, the chain of parents of the element.// i.e. [ {parent}, {grandparent}, {great-grandparent} ]varparent=document.getElementById(identifier).parentElement;varancs=[];while(parent){ancs.push({tagName: parent.tagName,identifier: parent.id});parent=parent.parentElement;}returnancs;},isEmpty: function(identifier){// Must return boolean.varelement=document.getElementById(identifier);return(element.textContent.trim()!==''||element.childElementCount>0);},// The functions above are needed for libcss-js to navigate your element tree.// The ones below are optional. If not provided, they always return false.isVisited: function(identifier){// Return boolean},isHover: function(identifier){// Return boolean},isActive: function(identifier){// Return boolean},isFocus: function(identifier){// Return boolean},isEnabled: function(identifier){// Return boolean},isDisabled: function(identifier){// Return boolean},isChecked: function(identifier){// Return boolean},isTarget: function(identifier){// Return boolean},isLang: function(identifier<string>,language<string>){// Return booleanvarelement=document.getElementById(identifier);return(element.lang===language);}});

libcss.addSheet(sheet, ?options)

Adds a CSS stylesheet to the selection context.

sheet<string> The CSS text to be parsed.

options<object>

• options.level <string>

  CSS level. Accepted values are '1', '2', '2.1' and '3'. Defaults to '3'.

• options.origin <string>

  CSS origin. Accepted values are 'author', 'user', 'ua', 'UA', 'user agent', 'user-agent' (the last four are equivalent). Defaults to 'author'.

• options.url <string>

  URL from which the CSS file was retrieved. Useful for loading resources with relative paths.

• options.media <array of strings>

  The media to apply the CSS rules. Accepted values of the string array are 'tv', 'tty', 'aural', 'print', 'screen', 'speech', 'braille', 'embossed', 'handheld', 'projection' and 'all'. Defaults to 'all'.

• options.allow_quirks <boolean>

  Attempt to parse poorly-formatted CSS. Use only if needed, because it may parse shorthands with undefined behavior. Defaults to false.

libcss.dropSheets()

Deletes all CSS from the selection context.

libcss.getStyle(identifier, ?options)

Returns an object containing all the computed style for the element that corresponds to the identifier. The returned object has the format { 'property': 'value', ... }. The available properties are defined upstream, by NetSurf's LibCSS.

options<object>

• options.pseudo <string>

  Pseudo element to be queried. Accepted values are 'none', 'first-line', 'first-letter', 'before' and 'after'. Defaults to 'none'.

• options.media <string>

  The medium being queried. Accepted values are 'tv', 'tty', 'aural', 'print', 'screen', 'speech', 'braille', 'embossed', 'handheld', 'projection' and 'all'. Defaults to 'all'.

Testing

npm run test