API overhaul (v1.0.0 preview)

[pygy]

This is the API rewrite I've already mentioned on Gitter, I'd love to get feedback on this before I merge it in.

Here are the main changes:

• Local namespaces are now per j2c instances.
• j2c.sheet() returns a plain string, not a wrapped new String().
• names are attached to j2c.names.
• j2c.inine shares the same namespace for animations.
• _j2c = j2c([ plugins | options]...) is a j2c instance factory.
• _j2c.use([plugins | options]...) works exaclty like the factory. The default j2c instance doesn't have use().

Pulgins work like this. A plugin can either be a function or an object, or an array of plugins (thus nested arrays are supported).

If it is a function, it is called with the instance as a sole argument, and can thus read and modify it. If it returns an object, that result is treated as if it were an object plugin.

If the plugin is an object, we iterate over its properties.

• If names is found, use the corresponding value to define names in the local namespace. Preexisting names are not overwritten (_.default stlye).
• If postprocess is found, push the corresponding value in the postprocessors array.
• Otherwise, decorate the instance with the key/vaule pair. Don't overwrite pre-existing methods. Thus, passing the upcoming j2c-color to use would add all the color methods wo the instance.

The idea is to put everytihng style-related inside the j2c instance, so that you can build it in one place, and just import/require one thing in your modules.

I'd imagine mithril-j2c for that version as a plugin that spies on sheet (wrap it) and add a view function to the j2c instance, for example.

What do you guys think?

[mithriljs-cn]

Please see below repo which use j2c to manage CSS themes:

https://github.com/mithriljs-cn/m_j2c

and a simple demo here

maybe can give you some ideas?

For now we use j2c to generate sheets from js obj, get new class names, and save internally for setNS/add/remove

+1 for j2c.names coze it's not handy to get names from new String()

[pygy]

@mithriljs-cn good stuff... You may want to avoid having m_j2c walk the vDOM recursively, and only localize the classes of the current element. Otherwise you can't use it to accept "foreign" vDOM (third party components), it may transform the class names in ways the third party author didn't anticipate...

---

Some progress on the v1 front... I realize that I'm likely to be the only one to use the plugin interface, at least at first, but I still like to at least expose my plans for it:

I've added the ability to tap into the buffer population on the fly rather than iterating over the buffer after the fact. It may or may not add a small overhead (the result vary from run to run), but it gives a much better interface, because you can target selectors, declarations and at-rules separately without any additional logic (I provide different hooks for these scenarios).

With the buffer post-processor, you had to carefully walk the buffer and detect whether you were facing an at rule (with or without block), a selector or a declaration. The new approach may faster too since you won't have to iterate over the buffer several times. It adds function call overheads, though, but I'm not sure they are significant.

[pygy]

Sorry for the noise, that was a badly configured bot...

[pygy]

Progress report on the v1.0.0 front:

• The ill-named @extend which should have been @composes since it matches the semantics of @tivac's modular-css quite closely has been removed and will be spun out to a plugin because I couldn't manage to implement it in a way that's general, reliable and concise. I went through several revisions, but never managed to find something satisfactory for a stable release. It will live on as a plugin while I find the best way to implement it, but I don't want it to block the v1 release anymore.
• I've added a plugin interface for additional at-rules, which will allow to work on @compose and other at rules (either to be passed to the sheet, like @document, or to do special things at the j2clevel like @mixin) while taking advantage of most of the j2c machinery. This requires me to expose what was up to this point private functions that walk the source tree. There may be some extra work to ensure that they present a sane signature to plugin authors.
• $filter plugins can now also access said machinery.
• The automatic -webkit- prefix additions for @keyframes, animation and animation-name have been moved to j2c-plugin-prefix-legacy. This simple version of the prefixer allowed to hone the $filter plugin API, and to build the infrastructure for the more complex, complete j2c-plugin-prefix plugin that's still WIP.

---

In parallel, I've been working on a ((synchronous PostCSS plugin) to (j2c filter)) adapter. That was surprisingly easy, and paves the way for server-side automatic prefix insertion (warpping autoprefixer should now be trivial).

At last, I've made progress on the PrefixFree port, which was harder to adapt (RegExps, two problems, yeah!), and isn't finisehd yet.The original builds RegExps dynamically for each invocation, which may not matter much when you're matching whole style sheets, but is not suitable when you match individual properties and selectors. Also, it ignores strings and comments and may accidentally modify their content. The likelihood of that causing problems is low but non-null, so better handling is necessary.

---

So now that the API is stable, I'll update the docs and release a beta. The final v1 will be released when the prefix plugin is ready, assuming no issues were raised in the mean time.

[codecov-io]

Codecov Report

❗ No coverage uploaded for pull request base (master@ff23110). Click here to learn what that means.
The diff coverage is 99.86%.

@@            Coverage Diff            @@
##             master      #15   +/-   ##
=========================================
  Coverage          ?   99.87%           
=========================================
  Files             ?        9           
  Lines             ?      770           
  Branches          ?      209           
=========================================
  Hits              ?      769           
  Misses            ?        1           
  Partials          ?        0

Impacted Files	Coverage Δ
plugins/prefix-browser/test-utils/misc.js	100% <100%> (ø)
plugins/prefix-browser/test-utils/exposed.js	100% <100%> (ø)
dist/j2c.commonjs.js	100% <100%> (ø)
plugins/prefix-browser/test-utils/mocks.js	100% <100%> (ø)
...lugins/prefix-browser/test-utils/ospec-instance.js	100% <100%> (ø)
plugins/postcss/test-utils/ospec-instance.js	100% <100%> (ø)
test-utils/sinks.js	100% <100%> (ø)
test-utils/ospec-instance.js	100% <100%> (ø)
plugins/postcss/src/index.js	98.78% <98.78%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ff23110...c3d3832. Read the comment docs.

[dead-claudia]

@pygy Just a quick question: have you added a "module": "dist/j2c.es6.js" field to the package.json? That would really help Rollup and Webpack users out, since they then don't have to remap it. (Filed #37 to address the current version.)

[pygy]

I'll rebase this branch on top of the main one, thanks for the PR