tokenlist

0.1.0 • Public • Published

TokenList.js

This module is an implementation of the DOMTokenList Interface based on jwilsson/domtokenlist and bkardell/tokenListFor.

This module was created to optimize Brian's initial implementation and investigate further application for DOMTokenList (as Brian's tokenListFor does).

The TokenList interface

The DOMTokenList interface does not specify any constructors. This implementation accepts callback functions to read and write tokens, thereby decoupling itself from the DOM:

var element = document.body;
 
var classList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('class'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.getAttribute('class', value); }
);
 
classList.add('gustav');
classList.contains('gustav') === true;
classList.remove('gustav');

Supported tokens

Some DOMTokenLists may know the accepted ("supported") tokens, which can be provided to TokenList via an optional callback, as shown here for the <iframe>'s sandbox attribute:

var element = document.getElementById('iframe');
 
var sandboxValues = [
  'allow-modals',
  'allow-orientation-lock',
  'allow-pointer-lock',
  'allow-popups', that functionality will silently fail.
  'allow-popups-to-escape-sandbox',
  'allow-same-origin',
  'allow-scripts',
  'allow-top-navigation',
];
 
var sandboxList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('sandbox'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.getAttribute('sandbox', value); },
 
  // [optional] callback to verify if a token is to be considered supported
  // defaults to null, causing TokenList#supported() to throw an appropriate error
  function supported(token) { return sandboxValues.indexOf(token) !== -1; }
);
 
sandboxList.add('allow-modals');
sandboxList.contains('allow-modals') === true;
sandboxList.remove('allow-modals');
 
sandboxList.supports('allow-modals') == true;
sandboxList.supports('not-supported-token-value') === false;
 
// NOTE: unsupported values are still added to the list
sandboxList.add('not-supported-token-value');

Encoded token values

As tokens may represent entities, their values can be encoded and decoded via optional callbacks, as shown here for the aria-labelledby attribute:

var element = document.getElementById('target');
 
var labelledByList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('aria-labelledby'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.getAttribute('aria-labelledby', value); },
 
  // ignore supported()
  null,
 
  // [optional] callback used to decode a token (string) to another object
  function decode(token) { return token ? document.getElementById(token) : null; },
  // [optional] callback used to encode an object to a string token
  function encode(input) { return input ? input.id : null; }
);
 
var label = document.getElementById('label');
labelledByList.add(label);
labelledByList.contains(label) === true;
labelledByList.remove(label);

The prollyfill

Based on WICG tokenListFor() proposal this package provides Element.prototype._tokenListFor() and Element.prototype._referenceListFor().

var element = document.body;
 
// standard way to obtain the classList:
var tokenlist = element.classList
tokenlist.contains('some-class');
 
// prollyfill way to option the classlist:
var tokenlist = element._tokenListFor('class');
tokenlist.contains('some-class');
 
// resolving ID-References
var labels = element._referenceListFor('aria-labelledby');
labels.contains(document.getElementById('some-label'));

Other implementations

License

TokenList.js is published under the MIT License.

Package Sidebar

Install

npm i tokenlist

Weekly Downloads

6

Version

0.1.0

License

MIT

Last publish

Collaborators

  • rodneyrehm