Merge pull request #3 from zgreen/at-rules

At rules

.babelrc

@@ -1 +1,4 @@
-{ "presets": ["es2015"] }
+{
+	"presets": ["es2015"],
+	"plugins": ["transform-flow-strip-types", "transform-object-rest-spread"]
+}

.eslintrc

@@ -0,0 +1,38 @@
+{
+  "extends": "standard",
+  "plugins": [
+    "flowtype"
+  ],
+  "parser": "babel-eslint",
+  "rules": {
+    "flowtype/define-flow-type": 1,
+    "flowtype/require-parameter-type": 1,
+    "flowtype/require-return-type": [
+      1,
+      "always",
+      {
+      "annotateUndefined": "never"
+      }
+    ],
+    "flowtype/space-after-type-colon": [
+      1,
+      "always"
+    ],
+    "flowtype/space-before-type-colon": [
+      1,
+      "never"
+    ],
+    "flowtype/type-id-match": [
+      1,
+      "^([A-Z][a-z0-9]+)+Type$"
+    ],
+    "flowtype/use-flow-type": 1,
+    "flowtype/valid-syntax": 1,
+    "import/prefer-default-export": 0
+  },
+  "settings": {
+    "flowtype": {
+      "onlyFilesWithFlowAnnotation": true
+    }
+  }
+}

.gitignore

@@ -1,4 +1,3 @@
 .DS_Store
 node_modules/
 npm-debug.log
-*.actual.css

.travis.yml

@@ -0,0 +1,3 @@
+language: node_js
+node_js:
+  - "node"

LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2016 Zachary Green <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,17 +1,22 @@
 # PostCSS Critical CSS
 
-This plugin allows you to define and output critical CSS using custom CSS properties.
+This plugin allows the user to define and output critical CSS using custom atRules, and/or custom CSS properties. Critical CSS may be output to one or more files, as defined within the plugin options or within the CSS.
 
 ## Install
 
 `npm install postcss-critical-css --save-dev`
 
-## Example
+## Examples
+
+A live example is available in this repo. See the `/example` directory, and use the command `npm run example` to test it out.
+
+### Using the `@critical` atRule
 
 ```css
 /* In foo.css */
+@critical;
+
 .foo {
-  critical-selector: this;
   border: 3px solid gray;
   display: flex;
   padding: 1em;
@@ -27,41 +32,63 @@ Will output:
 }
 ```
 
-Note that in the above example, the selector is rendered as it is written in the
-module. This may not be desireable, so you can alternatively identify the
-selector you'd like to use in your `critical.css`;
+### Using the `@critical` atRule with a custom file path
+
 ```css
 /* In foo.css */
+@critical bar;
+
 .foo {
-  critical-selector: .custom-selector;
   border: 3px solid gray;
   display: flex;
   padding: 1em;
 }
 ```
 Will output:
 ```css
-/* In critical.css */
-.custom-selector {
+/* In bar.css */
+.foo {
   border: 3px solid gray;
   display: flex;
   padding: 1em;
 }
 ```
 
-If you'd like to ouptut the entire scope of a module, including children, you can!
+### Using the `@critical` atRule with a subset of styles
+
 ```css
-/* in foo.css */
+/* In foo.css */
 .foo {
-  critical-selector: scope;
   border: 3px solid gray;
   display: flex;
   padding: 1em;
 }
 
-.foo a {
-  color: blue;
-  text-decoration: none;
+@critical {
+  .bar {
+    border: 10px solid gold;
+    color: gold;
+  }
+}
+```
+Will output:
+```css
+/* In bar.css */
+.bar {
+  border: 10px solid gold;
+  color: gold;
+}
+```
+
+### Using the custom property, `critical-selector`
+
+```css
+/* In foo.css */
+.foo {
+  critical-selector: this;
+  border: 3px solid gray;
+  display: flex;
+  padding: 1em;
 }
 ```
 Will output:
@@ -72,16 +99,31 @@ Will output:
   display: flex;
   padding: 1em;
 }
+```
 
-.foo a {
-  color: blue;
-  text-decoration: none;
+### Using the custom property, `critical-selector`, with a custom selector.
+
+```css
+/* In foo.css */
+.foo {
+  critical-selector: .bar;
+  border: 3px solid gray;
+  display: flex;
+  padding: 1em;
+}
+```
+Will output:
+```css
+/* In critical.css */
+.bar {
+  border: 3px solid gray;
+  display: flex;
+  padding: 1em;
 }
 ```
 
-And what if you need to output multiple critical CSS files
-(for example, if you have two different templates that do not share styles)?
-You can do that as well.
+### Using the custom property, `critical-filename`
+
 ```css
 /* in foo.css */
 .foo {
@@ -102,24 +144,50 @@ Will output:
 }
 ```
 
-## Options
+### Using the custom property, `critical-selector`, with value `scope`
+
+This allows the user to output the entire scope of a module, including children.
+
+```css
+/* in foo.css */
+.foo {
+  critical-selector: scope;
+  border: 3px solid gray;
+  display: flex;
+  padding: 1em;
+}
+
+.foo a {
+  color: blue;
+  text-decoration: none;
+}
+```
+Will output:
+```css
+/* In critical.css */
+.foo {
+  border: 3px solid gray;
+  display: flex;
+  padding: 1em;
+}
+
+.foo a {
+  color: blue;
+  text-decoration: none;
+}
+```
 
-**outputPath**
-Path to which critical CSS should be output
-Default: current working directory
+## Plugin options
 
-**preserve**
-Whether or not to remove selectors from primary CSS document once they've been marked as critical.
-This should prevent duplication of selectors across critical and non-critical CSS.
-WARNING: this is a destructive option and may break styles relying on the cascade!
-Default: true
+The plugin takes a single object as its only parameter. The following properties are valid:
 
-**minify**
-Minify output CSS
-Default: true
+| Arg          | Type      | Description                                 | Default |
+| ------------ | --------- | ------------------------------------------- | ------------------------- |
+| `outputPath` | `string`  | Path to which critical CSS should be output | Current working directory |
+| `preserve`   | `boolean` | Whether or not to remove selectors from primary CSS document once they've been marked as critical. This should prevent duplication of selectors across critical and non-critical CSS. | `true` |
+| `minify`     | `boolean` | Minify output CSS? | `true` |
 
 ## To Dos
 
-- Tests
 - More tests
 - More robust warnings

example/example.css

@@ -0,0 +1,16 @@
+@critical;
+
+.foo {
+  display: flex;
+  width: calc(100% - 200px);
+}
+
+.bar {
+  border: 10px solid gold;
+  height: 100%;
+}
+
+.baz::before {
+  content: 'test';
+  position: fixed;
+}

example/example.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+var fs = require('fs')
+var test = require('tape')
+var postcss = require('postcss')
+var postcssCriticalCSS = require('..');
+
+const basePath = `${process.cwd()}/example`;
+function cb (files) {
+  function useFileData (data, file) {
+    postcss([postcssCriticalCSS({outputPath: basePath})])
+      .process(data)
+      .then(result => fs.writeFile(
+        `${basePath}/${file.split('.')[0]}.non-critical.css`, result.css))
+  }
+  files.forEach(function(file) {
+    if (file === 'example.css') {
+      fs.readFile(`${basePath}/${file}`, 'utf8', (err, data) => {
+        if (err) {
+          throw new Error(err)
+        }
+        useFileData(data, file)
+      })
+    }
+  })
+}
+
+fs.readdir(basePath, 'utf8', (err, files) => {
+  if (err) {
+    throw new Error(err)
+  }
+  cb(files)
+})

example/example.non-critical.css

@@ -0,0 +1,14 @@
+.foo {
+  display: flex;
+  width: calc(100% - 200px);
+}
+
+.bar {
+  border: 10px solid gold;
+  height: 100%;
+}
+
+.baz::before {
+  content: 'test';
+  position: fixed;
+}