feat(format): output references #504

dbanksdesign · 2020-12-11T00:24:17Z

Issue #, if available: #17 #396

Description of changes: Allow for variable references in output files. These changes will make it easier to use the name of a referenced token rather than the resolved value, so the output will keep the aliases/references intact.

Adding resolveReference() and usesReference() methods on the dictionary object that is passed to formats and actions. This will allow custom formats and actions to test and resolve references the same way style dictionary does internally, allowing you to get the transformed name of a token for instance.
Adding a outputReferences configuration on SCSS, CSS, and Less variables, as well as ios/class.swift, flutter/class.dart, and android/resources formats to make use of this
Adding a 'output-references' example to show how to use these new methods
Added documentation about this feature
Added integration testing to properly test this

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

chazzmoney · 2020-12-11T00:51:02Z

WOOHOO! #17

chazzmoney · 2020-12-11T00:56:35Z

I really like that this empowers people on the route of #268, which is something that I have wanted for SD for a LONG time (even well before I created that issue).

I think it is super valuable that people can customize SD for how they think about tokens. It fits our usually conflicting goals: simply to use; fully customizable / working how people want or expect; enable and encourage people to build in a manner that organizes their thinking (use both base/defining properties and use-case/output properties).

This also enables client-side/end-platform tools to have strong access to the underlying reference structure that powers SD which is a huge plus.

Really really excited about this one.

chazzmoney · 2020-12-11T01:02:30Z

Three improvements to consider:

I think this deserves documentation catering to the absolute newest / least experienced SD user. This is a very important / useful thing and making sure people know it is available and can understand how to use it easily will help them use SD to its fullest.
Based on the usefulness to downstream tooling, we may want to make this "on" by default... this will be included in a major version/breaking change so it might be ok... we should probably @ some of our most active folks here to get their opinion.
The configuration options here should likely be able to be set at three levels: global, included file, and property (maybe even inheritably so)

chazzmoney · 2020-12-12T00:37:17Z

Also... we should probably update all default formats to use variables where appropriate.

It will be a lot of work, but it is weird to include this without updating all of them.

lib/common/formats.js

examples/advanced/variables-in-outputs/README.md

didoo · 2020-12-16T23:43:17Z

lib/utils/references/resolveReference.js

+    return;
+  }
+
+  for (i = 0; i < path.length; i++) {


now that it's been decided to move away from lodash, and the "utils" folder has started to contain lodash-like functions, do you think we should isolate this as deepFind function there?

didoo · 2020-12-16T23:55:10Z

First of all, amazing PR @dbanksdesign, really great idea 🙌.

Now, I did a quick code review and added a few comments there. I have some other thoughts here:

I am not entirely sure about the name useVariables. maybe there is something that could be more explicit on what it does? I was thinking something like preserve[References/Variables] or use[Variables|References]InOutput
agree with @chazzmoney that we should consider also other less-obvious default formats that may support this kind of referencing in output (which one? JS clearly yes, in some form; but what about others like formats for iOS or Android?)
regarding setting it on by default for version 3.0, agree as well, makes sense (unless there are downsides we're overlooking)
regarding the three levels configuration, not sure about it. why do you think we need this extra layer of complexity in the codebase? if you can achieve the result adding a set of useVariables: true wherever you need it for the output, I don't think is much of a burden for the final user, and in any case, you probably do it once at the initial setup and then forget.
regarding the documentation, there are other parts that we may want to highlight for the new user (eg. my colleague didn't realize the input format for the tokens could be directly JavaScript code, not only JSON) so maybe this could be done in a separate task?

Let me know if I can help somehow on this.

didoo · 2021-01-14T12:12:55Z

@dbanksdesign there may be a chance I need to use this in one of our projects. Is there a way I can help on this one (other reviews, code refactoring, add tests, etc?) so it gets approved and merged?

Co-authored-by: Cristiano Rastelli <public@didoo.net>

dbanksdesign · 2021-01-15T04:45:44Z

@didoo I would love some help with this! I think we need some more tests, more documentation, and updating applicable formats to use this new code. Whichever you'd like to help out on would be greatly appreciated. I also have some time tomorrow I can spend on this and you can take a look.

* 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

Adds basePxFontSize platform option which allows you to set the base px font size for pixel transforms. The default remains the same, 16.

…Props keys (#501) These descriptions are based on the `Default property metadata` section in the `Properties` docs.

…eferences

Note: This is a breaking change as it changes the behavior of SD from 2.x

dbanksdesign · 2021-01-26T00:10:28Z

Big update:

Changed the option name from 'useVariables' to 'keepReferences' so it better matches the methods
Moved the option to the options object in a file, to be consistent with other file-level configuration like showFileHeader
Updated android/resources format to handle keepReferences
Updated scss/variables format to handle keepReferences. In order to do this, because Sass is imperative, we are sorting the allProperties array so all references come last.
Addressed @didoo comment about indentation
Started to add integration testing to better test the output of formats.
Cleaned up some things in our testing

…d flutter

dbanksdesign · 2021-01-29T23:59:26Z

Another update:

Changed option name to outputReferences
Added Swift and Flutter support and integration tests
Started some documentation

chazzmoney · 2021-01-30T00:14:17Z

docs/formats.md

+  --color-danger: var(--color-red);
+  --color-error: var(--color-danger);
+}
+```


I love this as an example. You might contrast it with what happens if outputReferences is false.

chazzmoney · 2021-02-02T00:08:32Z

Nice work. Seriously. LGTM!

dbanksdesign · 2021-02-02T00:15:48Z

Update:

Added documentation in the config section about this
Platform level configuration can now define an options object with the same options as a file object, and the options cascade
Renamed the example

uptonking · 2021-02-19T17:01:27Z

@dbanksdesign
Is there any way to support generate css variables with fallback values?
tokens source:

{ 
  "color": {
    "background": {
      "primary": { 
		"value": "{color.palette.neutral.0.value}" ,
		"fallback":"red"
		}
    }
  }
}

tokens output:

/** simple css var */
--color-background-primary: var(--my-var, red);

/* complex var may not be necessary to be implemented */
--color-background-primary: var(--my-var, var(--my-background, pink));

#544 this issue seems similar.

It seems that I have to write custom format.

feat(format): adding ability to have variables in output

bce8484

didoo reviewed Dec 16, 2020

View reviewed changes

dbanksdesign and others added 2 commits January 14, 2021 12:28

Update examples/advanced/variables-in-outputs/README.md

6c27853

Co-authored-by: Cristiano Rastelli <public@didoo.net>

Update lib/common/formats.js

7422d0c

Co-authored-by: Cristiano Rastelli <public@didoo.net>

jbarreiros and others added 15 commits January 22, 2021 15:27

feat(transforms): add 'px to rem' transform (#491)

1d9d7f1

feat(format): adding android/resources format

bd1f583

chore(editorconfig): remove trailing line rule

e74c70f

fix(parsers): fixed an error where parsers weren't running (#511)

131a87d

refactor(transforms): add platform option 'basePxFontSize' (#505)

81799bc

Adds basePxFontSize platform option which allows you to set the base px font size for pixel transforms. The default remains the same, 16.

fix(types): fix transform options type #502

3e54b1e

chore(types): adds filePath and isSource to Prop and descriptions to …

8000a2b

…Props keys (#501) These descriptions are based on the `Default property metadata` section in the `Properties` docs.

chore(release): 3.0.0-rc.2

daee2cb

feat: react-native support (#512)

2422a8c

chore(updates): adding integration tests and renaming option to keepR…

45af48b

…eferences

feat(build-file): do not generate file if properties is empty (#494)

bc05773

Note: This is a breaking change as it changes the behavior of SD from 2.x

chore(deprecation): updating buffer call in base64 converter (#522)

c79341e

fix(examples): little typo (#518)

e922e15

Merge branch '3.0' into variable-output

429a2d3

dbanksdesign added 2 commits January 29, 2021 15:57

chore(tests): fixing failing unit test

21d92ff

chore(references): changing option name, adding docs, adding swift an…

b017a1e

…d flutter

dbanksdesign changed the title ~~feat(format): adding ability to have variables in output~~ feat(format): output references Jan 30, 2021

chazzmoney reviewed Jan 30, 2021

View reviewed changes

dbanksdesign added 2 commits February 1, 2021 14:12

feat(buildfile): properly handling platform and file level options

ca388ff

chore(docs): update docs with information on outputting references

5359699

chazzmoney merged commit 7e7889a into 3.0 Feb 2, 2021

chazzmoney mentioned this pull request Feb 2, 2021

Question: Is there a way to transform alias into css variables without resolving the actual value? #396

Closed

dbanksdesign deleted the variable-output branch March 12, 2021 22:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(format): output references #504

feat(format): output references #504

dbanksdesign commented Dec 11, 2020 •

edited

Loading

chazzmoney commented Dec 11, 2020

chazzmoney commented Dec 11, 2020 •

edited

Loading

chazzmoney commented Dec 11, 2020 •

edited

Loading

chazzmoney commented Dec 12, 2020

didoo Dec 16, 2020

didoo commented Dec 16, 2020

didoo commented Jan 14, 2021

dbanksdesign commented Jan 15, 2021

dbanksdesign commented Jan 26, 2021 •

edited

Loading

dbanksdesign commented Jan 29, 2021 •

edited

Loading

chazzmoney Jan 30, 2021

chazzmoney commented Feb 2, 2021

dbanksdesign commented Feb 2, 2021

uptonking commented Feb 19, 2021 •

edited

Loading

feat(format): output references #504

feat(format): output references #504

Conversation

dbanksdesign commented Dec 11, 2020 • edited Loading

chazzmoney commented Dec 11, 2020

chazzmoney commented Dec 11, 2020 • edited Loading

chazzmoney commented Dec 11, 2020 • edited Loading

chazzmoney commented Dec 12, 2020

didoo Dec 16, 2020

Choose a reason for hiding this comment

didoo commented Dec 16, 2020

didoo commented Jan 14, 2021

dbanksdesign commented Jan 15, 2021

dbanksdesign commented Jan 26, 2021 • edited Loading

dbanksdesign commented Jan 29, 2021 • edited Loading

chazzmoney Jan 30, 2021

Choose a reason for hiding this comment

chazzmoney commented Feb 2, 2021

dbanksdesign commented Feb 2, 2021

uptonking commented Feb 19, 2021 • edited Loading

dbanksdesign commented Dec 11, 2020 •

edited

Loading

chazzmoney commented Dec 11, 2020 •

edited

Loading

chazzmoney commented Dec 11, 2020 •

edited

Loading

dbanksdesign commented Jan 26, 2021 •

edited

Loading

dbanksdesign commented Jan 29, 2021 •

edited

Loading

uptonking commented Feb 19, 2021 •

edited

Loading