feat(filter): Added new filter removePrivate (#770)

* feat(dictionary): added filter removePrivate
* fix(lib): remove useless import
* docs(example): add basic documentation for filters
* docs(example): fix require of current styledictionary lib
* fix(example): adjust indentation
* docs(example): add information to filters README.md
* docs(example): improve basic documentation for custom filters
* fix(docs): add missing comment in index.js

closes #704

__tests__/common/filters.test.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with
+ * the License. A copy of the License is located at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+var filters = require('../../lib/common/filters');
+
+describe('common', () => {
+  describe('filters', () => {
+    describe('removePrivate', () => {
+      it('should keep a regular token in for distribution', () => {
+        var regularToken = {
+          name: 'color-border',
+          value: '#1a1aed'
+        }
+
+        expect(filters["removePrivate"](regularToken)).toEqual(true);
+      });
+
+      it('should keep an unfiltered token in for distribution', () => {
+        var unfilteredToken = {
+          name: 'color-border',
+          value: '#1a1aed',
+          private: false
+        }
+
+        expect(filters["removePrivate"](unfilteredToken)).toEqual(true);
+      });
+
+
+      it('should remove a filtered token from the distribution output', () => {
+        var filteredToken = {
+          name: 'color-border',
+          value: '#1a1aed',
+          private: true
+        }
+
+        expect(filters["removePrivate"](filteredToken)).toEqual(false);
+      });
+    });
+  });
+});

examples/advanced/custom-filters/.gitignore

@@ -0,0 +1,2 @@
+build/
+node_modules/

examples/advanced/custom-filters/README.md

@@ -0,0 +1,99 @@
+## Filters
+
+This example shows how to use built-in and custom filters to the design tokens.
+
+Filters are functions that might remove according to some conditions a design token from the output distribution.
+
+#### Running the example
+
+First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use *yarn* update the commands accordingly).
+
+At this point, if you want to build the tokens you can run `npm run build`. This command will generate the files in the `build` folder.
+
+#### How does it work a built-in filter?
+
+Currently StyleDictionary supports just the following built-in filters:
+
+- removePrivate
+
+You have to apply it in the `config.json` file:
+
+```
+"scss": {
+  "buildPath": "build/web/",
+  "files": [{
+    "destination": "colors.scss",
+    "filter": "removePrivate",
+    "format": "scss/variables"
+  }]
+}
+```
+
+The StyleDictionary will take care of filtering out proper design tokens from the source of truth:
+
+```
+{
+  "color": {
+    "gray": {
+      "light" : {
+        "value": "#CCCCCC",
+        "group": "color",
+        "private": true
+      },
+      "medium": {
+        "value": "#999999",
+        "group": "color"
+      },
+      "dark"  : {
+        "value": "#111111",
+        "group": "color"
+      }
+    },
+  }
+}
+```
+
+#### How does it work a custom filter?
+
+To declare a custom **filter**, you have to call the `registerFilter` method:
+
+```
+StyleDictionary.registerFilter({
+  name: 'isTextTransform',
+  matcher: function(token) {
+    return token.attributes.category === 'font' && token.value.includes['lowercase', 'uppercase]
+  }
+});
+```
+
+You have to apply it in the `config.json` file:
+
+```
+"scss": {
+  "buildPath": "build/web/",
+  "files": [{
+    "destination": "fonts.scss",
+    "filter": "isTextTransform",
+    "format": "scss/variables"
+  }]
+}
+```
+
+The StyleDictionary will take care of filtering out proper design tokens from the source of truth:
+
+```
+{
+  "fonts": {
+    "title-transform": {
+      "value": "uppercase", // included
+      "group": "font"
+    },
+    "title-size": {
+      "value": "36px", // excluded
+      "group": "font"
+    }
+  }
+}
+```
+
+More information can be found on the [documentation](https://amzn.github.io/style-dictionary/#/api?id=registerfilter).

examples/advanced/custom-filters/build.js

@@ -0,0 +1,27 @@
+const StyleDictionary = require('../../../index');
+
+console.log('Build started...');
+console.log('\n==============================================');
+
+
+// REGISTER THE CUSTOM FILTERS
+
+StyleDictionary.registerFilter({
+  name: 'removeBigSpacing',
+  matcher: function(token) {
+    return token.group === 'spacing' && token.value < 0.5
+  }
+});
+
+// APPLY THE CONFIGURATION
+// IMPORTANT: the registration of custom transforms
+// needs to be done _before_ applying the configuration
+const StyleDictionaryExtended = StyleDictionary.extend(__dirname + '/config.json');
+
+
+// FINALLY, BUILD ALL THE PLATFORMS
+StyleDictionaryExtended.buildAllPlatforms();
+
+
+console.log('\n==============================================');
+console.log('\nBuild completed!');

examples/advanced/custom-filters/config.json

@@ -0,0 +1,21 @@
+{
+  "source": ["tokens/**/*.json"],
+  "platforms": {
+    "web": {
+      "buildPath": "build/web/",
+      "files": [{
+        "destination": "tokens.js",
+        "filter": "removeBigSpacing",
+        "format": "javascript/es6"
+      }]
+    },
+    "scss": {
+      "buildPath": "build/web/",
+      "files": [{
+        "destination": "tokens.scss",
+        "filter": "removeBigSpacing",
+        "format": "scss/variables"
+      }]
+    }
+  }
+}