@dorgaren/usable

usable.js v0.2.0

Making the Web / DOM usable

The problem

Since Google, Apple and a few others hold the Web / DOM hostage (mainly through "WHATWG"), blocking useful evolutions while deliberately introducing dumb or egotistic changes, the whole model "evolved" into the split personality of a dystopian nightmare on one hand and being stuck in the '00s at the other.

This project is an attempt at turning (parts of) the DOM API into things both usable and consistent.

Installation, usage

First,

npm install @dorgaren/usable

then

require("@dorgaren/usable").install();

Please note that for this to work, you must absolutely load it before anything else, including lodash/underscore, jQuery, React, and Angular.

install() accepts an optional argument for the global object. If you run it in Node but have a window global for anything (else), or conversely, are using it in browser but having a global global reserved for something, you may hint at which global object to use, by choosing

require("@dorgaren/usable").install(window); // browser

or

require("@dorgaren/usable").install(global); // Node

explicitly.

Note: given the lack of native DOM support in Node, if you wish to use new DOM features, please use JSDOM as follows:

let jsDOM = require("js-dom");
require("@dorgaren/usable").install(global, { dom: jsDOM.window });

You should have similar success using an alternate DOM (like ShadowRoot, or even JSDOM) in a browser.

Please report any implementation / combination that does not work whilst you believe it should.

Not using Webpack/NPM?

In this case, I recommend that you use require.js. Download require.js and put it alongside your "site" script (here, site.js).

Replace the loading of your site script in the head with

    <script data-main="script/site" src="script/require.js"></script>

Then begin your "site" script with

requirejs([ "@dorgaren/usable" ], function(usable) { usable.install(); });

This way, anything you do with Usable will remain compatible when/if (ever) you switch to using a bundler.

Current aims

• An EventTarget that is actually reasonable in functionality
• DocumentFragment enhancements
• Dynamic HTMLCollection and NodeList
• ... (more to come)

Non-goals

There is stuff that would be great to make useful, but cannot really be touched from JS side. Some of these:

• Useful CSS dimension units (like ch, cw for "content height", "content width", or ph/pw for "parent height, parent width", respectively)
• ... (will add stuff here)

Do you have a basis for all this nonsense?

Surely enough, I will add details about the actual issues as I will have time, that is, by 1.0 hopefully. Please stay tuned until then. In general, however, apart from some rants, this project mainly tries to take its stance on the scientific, as opposed to the guru/religious side; so if the goals above don't tell you much, please don't bother.

Caveats

• Performance

Please note that some implementations here may not be the most optimal approaches, either in general, or on the specific platform you use.

This will definitely evolve over time, as long as the underlying proof-of-concept is viable.

• No support for "options" in "addEventListener"

Will follow soon (need to check the proposed inconsistencies across platforms).

FAQ

1. Why is this not in pure ES5 / ES6 / whatever syntax?

Most of the stuff that needs to be accessible for this kind of matter to work is either inaccessible or discouraged in ES6. Meanwhile, there are a lot of "syntactic sugars" that are generally useful in ES6, causing little to no ambiguity, and are supported

This should work natively in IE11 and anything from 2016 onwards.

Should you have any issues, though, just run this through some "transpiler". I tested it extensively with Buble.

2. Why slow / no minification / packaging etc?

Please consider all of this experimental before 1.0. That means that the core goals are warranted, but nothing else, neither expressed nor implied. This latter includes things like payload size or computational performance.

Note that the notion do not expect does not at all mean that they won't happen any sooner. Just do not fill the issues queue with stuff like that for the time being, please.

But please do open issues for anything extraordinary, i.e. if you find a platform that is like 10-100x slower using this than the others you tested.

3. Why CommonJS???

While this is supposed to work great in Node.js, its primary target is the browser.

Then again, to use such functionality, one needs ES5 syntax, that is, use object mangling, and the prototype approach.

In my opinion (yes, this is personal), ES module syntax looks very odd with prototype mangling.

Also, backwards compatibility is an internal requirement.

4. Node.js? There is not even native DOM support..

I suggest that you use JSDOM, as written in the example above.