necolas / dom-shims

Complete and well-tested shims / polyfills for various DOM API's missing in not-so-modern browsers

dom-shims

Complete and well-tested shims / polyfills for various DOM API's missing in not-so-modern browsers.

Installation

npm install --save dom-shims

Apply all the shims by requiring the module without assignment:

require('dom-shims');

Or apply specific shims:

require('dom-shims/shim/CustomEvent');
require('dom-shims/shim/Element.classList');
require('dom-shims/shim/Element.matches');

Features

Event polyfills

• CustomEvent constructor

Element.prototype shims

• Element#classList[1]
  • Element#length
  • Element#add(tokens...)
  • Element#contains(token)
  • Element#item(token)
  • Element#remove(tokens...)
  • Element#toggle(token, force)
• Element#closest
• Element#matches[2]

NOTES:

1. Ensures all browsers have classList support for SVG elements, multiple-argument support for add and remove, force-argument support for toggle, and correct length and item values even when the class value is mutated by means other than classList.

2. Patches IE 9's implementation, which lacks support for Elements not attached to the document.

Element mutation

DOM Level 4 mutation macros for:

parentNode:

• Element#append()
• Element#prepend()

childNode:

• Element#after()
• Element#before()
• Element#remove()
• Element#replace()

Other shims

• HTMLDocument

Browser support

Intended support for:

• Chrome
• Firefox
• IE9+
• Safari 6+
• Android 4+
• Safari iOS 5.1+
• Opera

Acknowledgements

Thanks to the following libraries for inspiration, ideas, and workarounds:

• Finanical-Times/polyfill-service
• Raynos/DOM-shim
• WebReflection/dom4

dom-shims's Issues

.toggle crashes IE 10/11 Win7 VM

Tested in IE 10 & 11 on Win7 VM from https://github.com/xdissent/ievms

When the shim is in place, the path I saw was:

1. Call toggle in app code
2. Enter DOMTokenListPrototype.toggle
3. Fall through to else branch
4. Call DOMTokenListPrototype.toggle
5. repeat steps 2-4 until "Out of stack space" error is thrown.

If I bypass calls to toggle, using something like el.classList[someTest ? 'add' : 'remove'](cssClass), no errors occur.

Firefox error: 'add' is read-only

Firefox 29.0.0 (Linux) ERROR
  TypeError: "add" is read-only
  at /home/travis/build/necolas/dom-shims/shim/Element.classList.js:51
Firefox 29.0.0 (Linux) ERROR
  TypeError: "add" is read-only
  at /home/travis/build/necolas/dom-shims/shim/Element.classList.js:51
Firefox 29.0.0 (Linux): Executed 0 of 0 ERROR (0.755 secs / 0 secs)

when running CustomEvent in strict mode, `window` is undefined

If the CustomEvent module is itself used in a strict mode environment (and all modules run in strict mode in ES6) window will be undefined.

This is because the value of this (the parameter to the outer function wrapper) is undefined in a null-reffed function call in strict mode (it's the global object in non-strict mode).

Two workarounds come to mind:

1. Always reference the window object directly (fails in node.js, but might be ok since this is a DOM shim)

2. Use an indirect eval call to access the global value:
   var window = (0, eval)('this');

Indirect evals are guaranteed to run in the global scope (and are safe):
http://perfectionkills.com/unnecessarily-comprehensive-look-into-a-rather-insignificant-issue-of-global-objects-creation/#ecmascript_5_strict_mode