doc updates

Author: ZeeCoder

.travis.yml

@@ -6,7 +6,7 @@ addons:
 script:
   - lerna bootstrap --ignore={demos}
   - yarn test:unit
-  - lerna run test
+  - yarn test:packages
   - node ./tests/bin/run-on-first-ci-job.js yarn test:integration:build
   - node ./tests/bin/run-on-first-ci-job.js yarn test:integration
 after_success: "yarn coveralls"

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# How to Contribute
+
+This project uses [Lerna](https://lernajs.io/) to manage its packages.
+
+## Getting Started
+
+I recommend [yarn](http://yarnpkg.com) for development.
+
+- Run `yarn`
+- Run `yarn bootstrap` (This will install all dependencies, build the packages
+  and links any cross-dependencies. It also allows packages to import each other
+  using their published package names.)
+- Run `yarn test:unit` to run the unit tests.
+- Run `yarn test:packages` to run the "test" scripts inside all packages.
+- Run `yarn test:integration:build` to build the integration test files.
+- Run `yarn test:integration` to run the integration tests in headless Chrome.
+
+## Testing
+
+Unit tests are using [Jest](https://jestjs.io/), while integration tests are using
+[Karma](https://karma-runner.github.io). (And [Sauce Labs](https://saucelabs.com/)
+in the CI to run in multiple browsers.)
+
+During development, you can run:
+
+- `yarn test:unit:watch` and,
+- `KARMA_CHROME=true yarn test:integration --singleRun=false`
+
+to run the tests on code changes.
+
+Note that you'll also need to run the build in watch mode in the package you're
+working on, as integration tests use the built code.)

docs/css-in-js.md

@@ -0,0 +1,28 @@
+# CSS-in-JS
+
+**This is not a "CSS-in-JS" library.**
+
+The sole purpose of this solution is to allow you to conditionally apply styles
+to child elements, inside a containing element.
+
+You can still use your regular CSS processing tool - be that PostCSS, SASS or LESS -
+to process your CSS files, and when certain styles are tied to a @container query
+with a certain condition, then it's the JS runtime that'll decide when to apply
+your them to the applicable elements.
+
+## Does it work with CSS-in-JS libraries?
+
+As I'm not using any of those libraries, I'm not exactly sure how the setup would
+look like, but it's quite possible to apply your regular / static styles with your
+library of choice, and then use the [meta builder](https://github.com/ZeeCoder/container-query/tree/master/packages/container-query-meta-builder)
+to build the meta object containing the styles that need to be applied runtime.
+
+Feeding such a meta object to the runtime is already what we're doing, the only
+difference being that this meta object is being conveniently generated for us by
+the [postcss-plugin](https://github.com/ZeeCoder/container-query/tree/master/packages/postcss-container-query).
+
+Looking into the tests for the meta builder might help you figure out how exactly
+this could be implemented.
+
+Don't hesitate to post in [issues](https://github.com/ZeeCoder/container-query/issues)
+if you feel like you have a good solution!

docs/css-modules.md

@@ -0,0 +1,102 @@
+# CSS Modules
+
+To make this library work with CSS Modules, we need to rewrite the class names in
+our meta object based on the styles object we get from CSS Modules on import.
+
+## Parcel
+
+With parcel, the setup is quite simple, as it supports PostCSS configuration
+files.
+
+The following shows a usual PostCSS setup, with container queries and CSS modules:
+
+```sh
+yarn add postcss-nested \
+         postcss-media-minmax \
+         @zeecoder/postcss-container-query \
+         postcss-modules --dev
+
+# or with NPM:
+
+npm install postcss-nested \
+            postcss-media-minmax \
+            @zeecoder/postcss-container-query \
+            postcss-modules --save-dev
+```
+
+Then put the following `.postcssrc` file in your root directory:
+
+```json
+{
+  "modules": true,
+  "plugins": {
+    "postcss-nested": { "bubble": ["container"] },
+    "postcss-media-minmax": {},
+    "@zeecoder/postcss-container-query": {},
+    "postcss-modules": {}
+  }
+}
+```
+
+Now you can do the following:
+
+```js
+import React, { Component } from "react";
+import styles, { meta as rawMeta } from "./App.css";
+import { ContainerQuery } from "@zeecoder/react-container-query";
+import { remapMetaSelectors } from "@zeecoder/container-query-meta-builder";
+
+// Since the container query postcss plugin comes before css-modules - and which
+// order we cannot change for technical reasons -, we need to remap class names
+// to the hashed class names CSS modules generates in the styles object.
+const meta = remapMetaSelectors(rawMeta, styles);
+
+class App extends Component {
+  render() {
+    return (
+      <ContainerQuery className={styles.App} meta={meta}>
+        My app.
+      </ContainerQuery>
+    );
+  }
+}
+
+export default App;
+```
+
+This would work the same way without react React, or without any component
+library for that matter.
+
+## With webpack
+
+Usage is the same with webpack, just add something like the following to your config:
+
+```js
+{
+    // ...
+    test: /\.css$/,
+    use: [
+      "style-loader",
+      {
+        loader: "css-loader",
+        options: {
+          modules: true
+        }
+      },
+      {
+        loader: "postcss-loader",
+        options: {
+          plugins: [
+            require("postcss-nested")({ bubble: ["container"] }),
+            require("postcss-media-minmax")(),
+            require("autoprefixer")(),
+            require("../packages/postcss-container-query/dist")()
+          ]
+        }
+      }
+    ]
+    // ...
+}
+```
+
+You can of course have the PostCSS setup in a config file for webpack as well.

package.json

@@ -49,6 +49,7 @@
     "webpack-cli": "^3.1.2"
   },
   "scripts": {
+    "test:packages": "lerna run test",
     "test:unit": "jest --coverage",
     "test:unit:watch": "jest --watch",
     "test:integration": "karma start",

tests/webpack.config.js

@@ -30,7 +30,7 @@ module.exports = {
         ]
       },
       {
-        test: /module.css$/,
+        test: /module\.css$/,
         use: [
           "style-loader",
           {