Draft usage transform.

documents/license.md

@@ -0,0 +1,4 @@
+## License
+
+<? @macro return require('./package.json').license; ?>
+

documents/links.md

@@ -0,0 +1,51 @@
+[trucks]: https://github.com/tmpfs/trucks
+[trucks-cli]: /packages/trucks-cli
+[skatejs]: https://github.com/skatejs/skatejs
+[webcomponents]: https://github.com/w3c/webcomponents
+[shadow-dom]: https://w3c.github.io/webcomponents/spec/shadow/
+[custom-elements]: https://www.w3.org/TR/custom-elements/
+[html-imports]: https://w3c.github.io/webcomponents/spec/imports/
+[html-templates]: https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+[polymer]: https://www.polymer-project.org/1.0/
+[react]: https://facebook.github.io/react/
+[react-webcomponents]: https://github.com/facebook/react/issues/5052
+[react-integration]: https://github.com/skatejs/react-integration
+[mozilla-webcomponents]: https://hacks.mozilla.org/2014/12/mozilla-and-web-components/
+[csp]: http://content-security-policy.com/
+[npm]: https://www.npmjs.com/
+[postcss]: https://github.com/postcss/postcss
+[mkdoc]: https://github.com/mkdoc/mkdoc
+[mkapi]: https://github.com/mkdoc/mkapi
+[mkparse]: https://github.com/mkdoc/mkparse
+[jshint]: http://jshint.com
+[jscs]: http://jscs.info
+
+[sources]: /packages/plugin-sources
+[load]: /packages/plugin-load
+[parse]: /packages/plugin-parse
+[transform]: /packages/plugin-transform
+[generate]: /packages/plugin-generate
+[write]: /packages/plugin-write
+
+[transform-csp]: /packages/transform-csp
+[bundle]: /packages/transform-bundle
+[copy]: /packages/transform-copy
+[skate]: /packages/transform-skate
+[stylus]: /packages/transform-stylus
+[less]: /packages/transform-less
+[sass]: /packages/transform-sass
+[trim]: /packages/transform-trim
+[tree]: /packages/transform-tree
+[style-extract]: /packages/transform-style-extract
+[style-inject]: /packages/transform-style-inject
+
+[resolver-core]: /packages/resolver-core
+[resolver-file]: /packages/resolver-file
+[resolver-http]: /packages/resolver-http
+[resolver-npm]: /packages/resolver-npm
+
+[less-css]: http://lesscss.org/
+[sass-css]: http://sass-lang.com/
+[stylus-css]: http://stylus-lang.com/
+[node-sass]: https://github.com/sass/node-sass
+[archy]: https://github.com/substack/node-archy

packages/transform-usage/.npmignore

@@ -0,0 +1,11 @@
+target
+build
+coverage
+package
+test
+doc
+mkdoc.js
+.jscsrc
+.jshintignore
+.jshintrc
+*.tgz

packages/transform-usage/README.md

@@ -0,0 +1,128 @@
+# Usage Transform
+
+> Generate component usage examples
+
+## Install
+
+```
+npm i trucks-transform-trim --save-dev
+```
+
+For the command line interface see [trucks-cli][].
+
+For each component module definition scan the input document for elements matching the component tag name and write them to usage HTML files.
+
+---
+
+- [Install](#install)
+- [Usage](#usage)
+- [API](#api)
+  - [trim](#trim)
+- [License](#license)
+
+---
+
+## Usage
+
+Use the `usage` key to configure this transform:
+
+```javascript
+const trucks = require('trucks');
+
+trucks(
+  {
+    files: ['components.html'],
+    transforms: ['usage'],
+    usage: {
+      main: false,
+      files: true
+    }
+  }, (err, state) => {
+    if(err) {
+      throw err; 
+    }
+    console.log(state);
+  }
+);
+```
+
+## API
+
+### trim
+
+```javascript
+public trim(state, conf)
+```
+
+Removes leading and trailing whitespace from inline styles and scripts.
+
+When the `lines` option is given each line is stripped of leading
+whitespace that matches the `pattern` regular expression.
+
+Returns map of visitor functions.
+
+* `state` Object compiler state.
+* `conf` Object transform plugin configuration.
+
+#### Options
+
+* `inline` Boolean=true only replace inline elements.
+* `lines` Boolean=true strip each line.
+* `templates` Boolean=false also trim template elements.
+
+## License
+
+MIT
+
+---
+
+Created by [mkdoc](https://github.com/mkdoc/mkdoc) on August 4, 2016
+
+[trucks]: https://github.com/tmpfs/trucks
+[trucks-cli]: https://github.com/tmpfs/trucks/blob/master/packages/trucks-cli
+[skatejs]: https://github.com/skatejs/skatejs
+[webcomponents]: https://github.com/w3c/webcomponents
+[shadow-dom]: https://w3c.github.io/webcomponents/spec/shadow/
+[custom-elements]: https://www.w3.org/TR/custom-elements/
+[html-imports]: https://w3c.github.io/webcomponents/spec/imports/
+[html-templates]: https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+[polymer]: https://www.polymer-project.org/1.0/
+[react]: https://facebook.github.io/react/
+[react-webcomponents]: https://github.com/facebook/react/issues/5052
+[react-integration]: https://github.com/skatejs/react-integration
+[mozilla-webcomponents]: https://hacks.mozilla.org/2014/12/mozilla-and-web-components/
+[csp]: http://content-security-policy.com/
+[npm]: https://www.npmjs.com/
+[postcss]: https://github.com/postcss/postcss
+[mkdoc]: https://github.com/mkdoc/mkdoc
+[mkapi]: https://github.com/mkdoc/mkapi
+[mkparse]: https://github.com/mkdoc/mkparse
+[jshint]: http://jshint.com
+[jscs]: http://jscs.info
+[sources]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-sources
+[load]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-load
+[parse]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-parse
+[transform]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-transform
+[generate]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-generate
+[write]: https://github.com/tmpfs/trucks/blob/master/packages/plugin-write
+[transform-csp]: https://github.com/tmpfs/trucks/blob/master/packages/transform-csp
+[bundle]: https://github.com/tmpfs/trucks/blob/master/packages/transform-bundle
+[copy]: https://github.com/tmpfs/trucks/blob/master/packages/transform-copy
+[skate]: https://github.com/tmpfs/trucks/blob/master/packages/transform-skate
+[stylus]: https://github.com/tmpfs/trucks/blob/master/packages/transform-stylus
+[less]: https://github.com/tmpfs/trucks/blob/master/packages/transform-less
+[sass]: https://github.com/tmpfs/trucks/blob/master/packages/transform-sass
+[trim]: https://github.com/tmpfs/trucks/blob/master/packages/transform-trim
+[tree]: https://github.com/tmpfs/trucks/blob/master/packages/transform-tree
+[style-extract]: https://github.com/tmpfs/trucks/blob/master/packages/transform-style-extract
+[style-inject]: https://github.com/tmpfs/trucks/blob/master/packages/transform-style-inject
+[resolver-core]: https://github.com/tmpfs/trucks/blob/master/packages/resolver-core
+[resolver-file]: https://github.com/tmpfs/trucks/blob/master/packages/resolver-file
+[resolver-http]: https://github.com/tmpfs/trucks/blob/master/packages/resolver-http
+[resolver-npm]: https://github.com/tmpfs/trucks/blob/master/packages/resolver-npm
+[less-css]: http://lesscss.org/
+[sass-css]: http://sass-lang.com/
+[stylus-css]: http://stylus-lang.com/
+[node-sass]: https://github.com/sass/node-sass
+[archy]: https://github.com/substack/node-archy
+

packages/transform-usage/doc/readme.md

@@ -0,0 +1,20 @@
+# Usage Transform
+
+> Generate component usage examples
+
+<? @include {=readme} install.md ?>
+
+For each component module definition scan the input document for elements matching the component tag name and write them to usage HTML files.
+
+***
+<!-- @toc -->
+***
+
+<? @include {=readme} usage.md ?>
+
+## API
+
+<? @exec mkapi src/index.js --level=3 ?>
+
+<? @include ../../../documents/license.md ?>
+<? @include ../../../documents/links.md ?>

packages/transform-usage/doc/readme/install.md

@@ -0,0 +1,6 @@
+## Install
+
+```
+npm i trucks-transform-usage --save-dev
+```
+

packages/transform-usage/doc/readme/usage.js

@@ -0,0 +1,17 @@
+const trucks = require('../../../../lib/index');
+
+trucks(
+  {
+    files: ['components.html'],
+    transforms: ['usage'],
+    usage: {
+      main: false,
+      files: true
+    }
+  }, (err, state) => {
+    if(err) {
+      throw err; 
+    }
+    console.log(state);
+  }
+);

packages/transform-usage/doc/readme/usage.md

@@ -0,0 +1,6 @@
+## Usage
+
+Use the `usage` key to configure this transform:
+
+<? @source {javascript=s/(\.\.\/)+lib\/index/trucks/gm} usage.js ?>
+

packages/transform-usage/mkdoc.js

@@ -0,0 +1,30 @@
+var mk = require('mktask');
+
+function doc(src, dest, opts, cb) {
+  mk.doc(src)
+    .pipe(mk.pi())
+    .pipe(mk.ref())
+    .pipe(mk.abs())
+    .pipe(mk.msg())
+    .pipe(mk.toc(opts.toc))
+    //.pipe(mk.ast.stringify())
+    //.pipe(process.stdout)
+    .pipe(mk.out())
+    .pipe(mk.dest(dest))
+    .on('finish', cb);
+}
+
+// @task readme build the readme file
+function readme(cb) {
+  doc(
+    'doc/readme.md', 'README.md',
+    {toc: {depth: 2, max: 3}}, cb);
+}
+
+// @task docs build all docs
+function docs(cb){
+  cb();
+}
+
+mk.task(readme);
+mk.task([readme], docs)

packages/transform-usage/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "trucks-transform-usage",
+  "version": "1.0.0",
+  "description": "Generate component usage examples",
+  "author": "muji <noop@xpm.io>",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tmpfs/trucks"
+  },
+  "engines": {
+    "node": ">=4.0"
+  },
+  "devDependencies": {
+    "babel-cli": "~6.10.1",
+    "babel-preset-es2015": "~6.9.0",
+    "chai": "~3.5.0",
+    "istanbul": "~0.4.4",
+    "mocha": "~2.5.3",
+    "trucks-compiler": "*"
+  },
+  "scripts": {
+    "clean": "rm -rf coverage target lib",
+    "build": "babel --presets es2015 src --out-dir lib",
+    "prepublish": "npm run build",
+    "lint": "jshint src test doc && jscs src test/spec",
+    "target": "rm -rf target && mkdir target",
+    "pretest": "npm run target",
+    "test": "NODE_ENV=test mocha ${SPEC:-test/spec}",
+    "precover": "npm run pretest",
+    "cover": "NODE_ENV=test istanbul cover _mocha -- ${SPEC:-test/spec}"
+  }
+}

packages/transform-usage/src/index.js

@@ -0,0 +1,57 @@
+/**
+ *  Output HTML files for component usage examples.
+ *
+ *  @public {function} usage
+ *  @param {Object} state compiler state.
+ *  @param {Object} conf transform plugin configuration.
+ *  @option {String=usage.html} [name] name of the output file.
+ *  @option {Boolean=true} [main] write all usage examples to a main file.
+ *  @option {Boolean=true} [file] write a file for each component module.
+ *  @option {String} [dir] override the default output directory.
+ *
+ *  @returns map of visitor functions.
+ */
+function usage(state, conf) {
+
+  const options = state.options
+      , opts = options.usage || conf;
+
+  let name = opts.name === String(opts.name) ? opts.name : 'usage.html'
+    , main = opts.main !== undefined ? opts.main : true
+    , file = opts.file !== undefined ? opts.file : true;
+
+  function onModule(node, cb) {
+    const selector = node.id
+        , elements = node.vdom(selector).toArray();
+
+    let componentName = node.id + '.' + name
+      , mainFile
+      , componentFile;
+
+    if(main) {
+      mainFile = state.getFile(name, opts.dir || options.out); 
+    }
+
+    if(file) {
+      componentFile = state.getFile(componentName, options.dir || options.out); 
+    }
+
+    elements.forEach((el) => {
+      const contents = node.vdom.html(el);
+      if(mainFile) {
+        mainFile.append(contents);
+      }
+
+      if(componentFile) {
+        componentFile.append(contents);
+      }
+    })
+    cb();
+  }
+
+  return {
+    Module: onModule
+  }
+}
+
+module.exports = usage;

packages/transform-usage/test/mocha.opts

@@ -0,0 +1,5 @@
+-u bdd
+--recursive
+--bail
+--reporter list
+-A