From d123e2a57400ddc7ea1a67d166f701fb24a54e11 Mon Sep 17 00:00:00 2001 From: Danny Banks Date: Mon, 7 Dec 2020 16:50:00 -0800 Subject: [PATCH 1/5] fix(extend): use given file path for token data --- __tests__/extend.test.js | 15 +++++++++++++++ lib/utils/combineJSON.js | 5 +++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/__tests__/extend.test.js b/__tests__/extend.test.js index afd940f88..1c50bd6e8 100644 --- a/__tests__/extend.test.js +++ b/__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, diff --git a/lib/utils/combineJSON.js b/lib/utils/combineJSON.js index 036ac50c2..8a364cb9c 100644 --- a/lib/utils/combineJSON.js +++ b/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; } From a9833d30de2230f81eee2bb0eb2d976601345544 Mon Sep 17 00:00:00 2001 From: Danny Banks Date: Mon, 14 Dec 2020 16:59:09 -0800 Subject: [PATCH 2/5] docs(properties): update properties doc to reflect new additions --- docs/properties.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/properties.md b/docs/properties.md index 81f99b28b..1b4a526ff 100644 --- a/docs/properties.md +++ b/docs/properties.md @@ -109,4 +109,48 @@ 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. +| filePath | String | The relative file path of the file the token is defined in. +| isSource | Boolean | If the token is from a file in the `source` array as opposed to `include`. + +This: + +```json5 +{ + "color": { + "background": { + "primary": { "value": "#fff" } + } + } +} +``` + +becomes: + +```json5 +{ + "color": { + "background": { + "primary": { + "name": "primary", + "path": ["color","background","primary"], + "original": { + "value": "#fff" + }, + "filePath": "tokens/color/background.json", + "isSource": true + } + } + } +} +``` + ---- From bddc2010404bb29307a64fcc694024b078b69bf3 Mon Sep 17 00:00:00 2001 From: Danny Banks Date: Wed, 16 Dec 2020 15:49:55 -0800 Subject: [PATCH 3/5] docs(property): adding default metadata to property docs --- docs/formats.md | 2 ++ docs/properties.md | 4 ++-- docs/transforms.md | 2 +- scripts/handlebars/templates/formats.hbs | 2 ++ scripts/handlebars/templates/transforms.hbs | 2 +- 5 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/formats.md b/docs/formats.md index 72c0fec3a..b0cde4e6e 100644 --- a/docs/formats.md +++ b/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: diff --git a/docs/properties.md b/docs/properties.md index 1b4a526ff..5b35b6043 100644 --- a/docs/properties.md +++ b/docs/properties.md @@ -123,7 +123,7 @@ Style Dictionary adds some metadata on each property that helps with transforms This: -```json5 +```json { "color": { "background": { @@ -135,7 +135,7 @@ This: becomes: -```json5 +```json { "color": { "background": { diff --git a/docs/transforms.md b/docs/transforms.md index 8337435d4..f005cecc0 100644 --- a/docs/transforms.md +++ b/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 help with transforms. ## Pre-defined Transforms diff --git a/scripts/handlebars/templates/formats.hbs b/scripts/handlebars/templates/formats.hbs index 03ea71029..73239fc09 100644 --- a/scripts/handlebars/templates/formats.hbs +++ b/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: diff --git a/scripts/handlebars/templates/transforms.hbs b/scripts/handlebars/templates/transforms.hbs index 623c097d3..711f68941 100644 --- a/scripts/handlebars/templates/transforms.hbs +++ b/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 help with transforms. ## Pre-defined Transforms From d1bc51773363ae98c3ea1489e4f41aac121a9d34 Mon Sep 17 00:00:00 2001 From: Danny Banks Date: Thu, 17 Dec 2020 09:49:24 -0800 Subject: [PATCH 4/5] docs(properties): adding more context to default metadata --- docs/properties.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/properties.md b/docs/properties.md index 5b35b6043..0f5b3f0fd 100644 --- a/docs/properties.md +++ b/docs/properties.md @@ -117,13 +117,23 @@ Style Dictionary adds some metadata on each property that helps with transforms | :--- | :--- | :--- | | 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. -| filePath | String | The relative file path of the file the token is defined in. -| isSource | Boolean | If the token is from a file in the `source` array as opposed to `include`. +| 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). -This: +Given this configuration: ```json +{ + "source": ["tokens/**/*.json"] + //... +} +``` + +This source file: + +```json +// tokens/color/background.json { "color": { "background": { @@ -141,6 +151,7 @@ becomes: "background": { "primary": { "name": "primary", + "value": "#fff", "path": ["color","background","primary"], "original": { "value": "#fff" From 3a2c194174f5cb91e1feb6ab8b85c7e09ff19be3 Mon Sep 17 00:00:00 2001 From: Danny Banks Date: Thu, 17 Dec 2020 09:57:33 -0800 Subject: [PATCH 5/5] docs(properties): cleaning up default metadata docs --- docs/transforms.md | 2 +- scripts/handlebars/templates/transforms.hbs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/transforms.md b/docs/transforms.md index f005cecc0..6052d371e 100644 --- a/docs/transforms.md +++ b/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). Style Dictionary adds some [default metadata](properties.md?id=default-property-metadata) to each property/token to help with transforms. +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 diff --git a/scripts/handlebars/templates/transforms.hbs b/scripts/handlebars/templates/transforms.hbs index 711f68941..b5b50047d 100644 --- a/scripts/handlebars/templates/transforms.hbs +++ b/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). Style Dictionary adds some [default metadata](properties.md?id=default-property-metadata) to each property/token to help with transforms. +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