README.md

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.setAttribute('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.setAttribute('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.setAttribute('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

• jwilsson/domtokenlist is a polyfill for classList and relList also works for SVG. Works with browser globals.
• Alhadis/DOMTokenList is a polyfill for classList and relList also works for SVG and supports "live collections". Does not include unit tests. Does not expose DOMTokenList implementation for other applications. Uses deprecated DOMAttrModified on SVG polyfill. Trips over unicode whitespace. Weird choice of code style.
• necolas/dom-shims specifically Element.classList.js and DomTokenList.js. CommonJS module. Trips over unicode whitespace.
• bkardell/tokenListFor is an implementation for the WICG tokenListFor() proposal. Does not include unit tests. Trips over unicode whitespace.

License

TokenList.js is published under the MIT License.