-
Notifications
You must be signed in to change notification settings - Fork 550
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
Comments
These are great discussion points. I think there are 2 use-cases in general at play here:
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. |
Your suggestion of 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. |
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' |
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? |
@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. |
+1 |
LGTM, thanks! |
Some of the formats (e.g.
scss/variables
javascript/es6
) output flat dictionaries keyed by each properties name (as specified by a name transform likename/cti/camel
). Other formats output the entire dictionary (e.g.javascript/umd
orjson
) along with all the internal metadata. This behavior was surprising to me (despite the fact that I addedjavascript/umd
myself heh). Here are a couple things I would expect from formatters: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?
The text was updated successfully, but these errors were encountered: