fix(extend): use given file path for token data (#499)

* fix(extend): use given file path for token data
* docs(properties): update properties doc to reflect new additions
* docs(property): adding default metadata to property docs
* docs(properties): adding more context to default metadata
* docs(properties): cleaning up default metadata docs

__tests__/extend.test.js

@@ -156,6 +156,21 @@ describe('extend', () => {
       expect(StyleDictionaryExtended.properties).toEqual(output);
     });
 
+    it('should use relative filePaths for the filePath property', () => {
+      var filePath = "__tests__/__properties/paddings.json";
+      var StyleDictionaryExtended = StyleDictionary.extend({
+        "source": [filePath]
+      });
+      var output = helpers.fileToJSON(__dirname + "/__properties/paddings.json");
+      traverseObj(output, (obj) => {
+        if (obj.value && !obj.filePath) {
+          obj.filePath = filePath;
+          obj.isSource = true;
+        }
+      });
+      expect(StyleDictionaryExtended.properties).toEqual(output);
+    });
+
     it('should override existing properties source is given', () => {
       var StyleDictionaryExtended = StyleDictionary.extend({
         properties: test_props,

docs/formats.md

@@ -71,6 +71,8 @@ A special file configuration is `filter`, which will filter the tokens before th
 }
 ```
 
+The token/property that is passed to the filter function has already been [transformed](transforms.md) and has [default metadata](properties.md?id=default-property-metadata) added by Style Dictionary.
+
 ### Creating formats
 
 You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object. Using this, you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like:

docs/properties.md

@@ -109,4 +109,59 @@ You can organize and name your style properties however you want, **there are no
 
 Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI structure to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'.
 
+## Default property metadata
+
+Style Dictionary adds some metadata on each property that helps with transforms and formats. Here is what Style Dictionary adds onto each property:
+
+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| name | String | A default name of the property that is set to the key of the property.
+| path | Array[String] | The object path of the property. `color: { background: primary: {value: "#fff"}}` will have a path of `['color','background', 'primary']`.
+| original | Object | A pristine copy of the original property object. This is to make sure transforms and formats always have the unmodified version of the original property.
+| filePath | String | The file path of the file the token is defined in. This file path is derived from the `source` or `include` file path arrays defined in the [configuration](config.md).
+| isSource | Boolean | If the token is from a file defined in the `source` array as opposed to `include` in the [configuration](config.md).
+
+Given this configuration:
+
+```json
+{
+  "source": ["tokens/**/*.json"]
+  //...
+}
+```
+
+This source file:
+
+```json
+// tokens/color/background.json
+{
+  "color": {
+    "background": {
+      "primary": { "value": "#fff" }
+    }
+  }
+}
+```
+
+becomes:
+
+```json
+{
+  "color": {
+    "background": {
+      "primary": {
+        "name": "primary",
+        "value": "#fff",
+        "path": ["color","background","primary"],
+        "original": {
+          "value": "#fff"
+        },
+        "filePath": "tokens/color/background.json",
+        "isSource": true
+      }
+    }
+  }
+}
+```
+
 ----

docs/transforms.md

@@ -32,7 +32,7 @@ There are 3 types of transforms: attribute, name, and value.
 **Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function that filter which properties that transform runs on. This allows us to only run a color transform on only the colors and not every property.
 
 ## Defining Custom Transforms
-You can define custom transforms with the [`registerTransform`](api.md#registertransform).
+You can define custom transforms with the [`registerTransform`](api.md#registertransform). Style Dictionary adds some [default metadata](properties.md?id=default-property-metadata) to each property/token to provide context that may be useful for some transforms.
 
 ## Pre-defined Transforms
 

lib/utils/combineJSON.js

@@ -50,7 +50,8 @@ function combineJSON(arr, deep, collision, source, parsers=[]) {
   }
 
   for (i = 0; i < files.length; i++) {
-    var resolvedPath = resolveCwd(path.isAbsolute(files[i]) ? files[i] : './' + files[i]);
+    var filePath = files[i];
+    var resolvedPath = resolveCwd(path.isAbsolute(filePath) ? filePath : './' + filePath);
     var file_content = null;
 
     try {
@@ -80,7 +81,7 @@ function combineJSON(arr, deep, collision, source, parsers=[]) {
     // Add some side data on each property to make filtering easier
     traverseObj(file_content, (obj) => {
       if (obj.value && !obj.filePath) {
-        obj.filePath = resolvedPath;
+        obj.filePath = filePath;
 
         obj.isSource = source || source === undefined ? true : false;
       }

scripts/handlebars/templates/formats.hbs

@@ -67,6 +67,8 @@ A special file configuration is `filter`, which will filter the tokens before th
 }
 ```
 
+The token/property that is passed to the filter function has already been [transformed](transforms.md) and has [default metadata](properties.md?id=default-property-metadata) added by Style Dictionary.
+
 ### Creating formats
 
 You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object. Using this, you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like:

scripts/handlebars/templates/transforms.hbs

@@ -28,7 +28,7 @@ There are 3 types of transforms: attribute, name, and value.
 **Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function that filter which properties that transform runs on. This allows us to only run a color transform on only the colors and not every property.
 
 ## Defining Custom Transforms
-You can define custom transforms with the [`registerTransform`](api.md#registertransform).
+You can define custom transforms with the [`registerTransform`](api.md#registertransform). Style Dictionary adds some [default metadata](properties.md?id=default-property-metadata) to each property/token to provide context that may be useful for some transforms.
 
 ## Pre-defined Transforms