Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inconsistent/unexpected behavior of formats #58

Closed
elliotdickison opened this issue Feb 13, 2018 · 7 comments
Closed

Inconsistent/unexpected behavior of formats #58

elliotdickison opened this issue Feb 13, 2018 · 7 comments
Labels
Core Architecture This is an issue related to the core architecture of Style Dictionary

Comments

@elliotdickison
Copy link

Some of the formats (e.g. scss/variables javascript/es6) output flat dictionaries keyed by each properties name (as specified by a name transform like name/cti/camel). Other formats output the entire dictionary (e.g. javascript/umd or json) along with all the internal metadata. This behavior was surprising to me (despite the fact that I added javascript/umd myself heh). Here are a couple things I would expect from formatters:

  • They respect any name transforms I supply to them
  • They output only transformed property values, not internal dictionary metadata etc.

I don't know if these are reasonable expectations or, if so, what the best solution is. I mostly wanted to get the conversation started because it feels like the current state is inconsistent and makes certain usages impossible (e.g. getting a umd module with nice camelCaseProperties).

One potential solution: Any format that supports nested data structures (e.g. json, js) should use those structures IFF a name transform is not supplied. If a name transform is supplied then they should output flat data structures using the names that result from the name transform. The data under each key should always be just the transformed property value and should not include any dictionary metadata. If the user needs a raw dump of the dictionary they could use the actions API.

What are your thoughts? Am I just misunderstanding the API here?

@dbanksdesign
Copy link
Member

dbanksdesign commented Feb 13, 2018

These are great discussion points. I think there are 2 use-cases in general at play here:

  1. Using the style dictionary as flat properties
  2. Using the style dictionary as an object

The all formatters do respect the name transform, but for formats that output an object-style dictionary (JSON, javascript/umd), 'name' is just an attribute on the property rather than an accessor. You can still get the name by going down the object like size.padding.base.name which would give you SizePaddingBase, although I don't know why that would be useful... It is a little confusing with name transforms and the object structure, as the 'name' of a property is just some form of the object path to that property like SizePaddingBase or size-padding-base.

What if we had 2 different formats for files that could support the object data structure or flat array and name them differently. For example, we could have 'json/object' and 'json/flat'. 'json/object' would be what 'json' is today, and 'json/flat' would output a json file like this:

{
  "SizePaddingBase": "10px",
  "SizePaddingLarge": "20px",
}

To your other point about all the metadata, it is a bit weird and heavy to output all that stuff. It is useful to have all that data if you are building documentation based on a style dictionary. Maybe being more explicit in naming the formats would help, we could have 'json/dictionary' format that outputs the full dictionary with meta data and everything.

@elliotdickison
Copy link
Author

Your suggestion of json/object, json/flat, and json/dictionary would cover all the use-cases that I can think of and seems like the simplest solution. A couple suggestions though: I think "nested" would be a clearer term than "object", and the term "raw" (or something else like it?) could be a more specific alternative to "dictionary" since they're all technically dictionaries.

One additional thought: Are these formatters starting to blur the lines between formatters and transformers? I had been thinking of the role of formatters as pretty simple functions that take the transformed dictionary and some sort of template and merge the two. The nested/flat/dictionary distinction seems like something that I would expect transformers to do, as they're the explicit API for transforming/shaping the data before it's output. Just food for thought, your proposed solution looks like a step in the right direction and doesn't involve any re-architecting so I would still go ahead with that.

@dbanksdesign
Copy link
Member

Good point, I think the weirdness is because of 'name' transforms, or having properties/tokens have a 'name' at all. Because a style dictionary is a structured object with properties/tokens being the leaf nodes that have a 'value', the name/how to access the token is implicit in the structure. When converting this to a usable file (like an Android resource xml file), sometimes it needs to be flattened, and other times it doesn't. Only when it needs to be flattened does a 'name' make any sense...

Maybe a 'name' transform doesn't make sense as a 'transform' per-se, but should be part of formatter/template in the future? This would allow platforms to be more easily broken up if they want to use different formats that might need different types of names...

Let's continue to think about it and maybe for a major release, as it would be an API change to transforms and formatters.

For now, I like the idea of making 'json/nested', 'json/raw', and 'json/flat'

@chazzmoney
Copy link
Collaborator

chazzmoney commented Feb 25, 2018

I'm also on board with the 'json/nested', 'json/raw', 'json/flat' plan.

Any other thoughts on this before we start in on this?

@chazzmoney chazzmoney added this to the 2.2 milestone Apr 17, 2018
@chazzmoney chazzmoney added the Core Architecture This is an issue related to the core architecture of Style Dictionary label Jun 6, 2018
This was referenced Oct 1, 2018
@dbanksdesign dbanksdesign removed this from the 2.3 milestone Oct 4, 2018
@chazzmoney
Copy link
Collaborator

@elliotdickison @dbanksdesign I think we solved a specific problem with the naming on JSON and sass formats. I was going to see if you all thought we should close this issue, or if there was a larger / higher level question about the data in formats and the naming.

@didoo
Copy link
Contributor

didoo commented Nov 9, 2018

Maybe being more explicit in naming the formats would help, we could have 'json/dictionary' format that outputs the full dictionary with meta data and everything.

+1

@elliotdickison
Copy link
Author

elliotdickison commented Nov 15, 2018

LGTM, thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Core Architecture This is an issue related to the core architecture of Style Dictionary
Projects
None yet
Development

No branches or pull requests

4 participants