feat: config option for math fraction digits

[Razinsky]

Fixes #289

This PR adds a new platform config option called mathFractionDigits to control the rounding of values when resolving math.

The current hardcoded value found here is 3 and one could potentially need this value to be any number.

⚠️ I suggest making the default value 4 as it tends to make more sense when trying to convert px to em and rem, but this is debatable. We might prefer to avoid breaking changes and keep 3 as default.

The variable name mathFractionDigits was borrowed from the .toFixed() function whose first argument is fractionDigits to which I prepended math for better context in relationship with the TS transform resolveMath. This is also to be discussed.

Usage

/* Style Dictionary config */
{
  platforms: {
    css: {
      options: {
        mathFractionDigits: 3
      },
      ...
    }
    ...
  }
}

[changeset-bot]

🦋 Changeset detected

Latest commit: c8e5203

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tokens-studio/sd-transforms	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jorenbroekema]

Great! I cleaned things up a bit:

• changed to unit test, from v4 style-dictionary is much more unit-testable since we don't have to write our outputs to the filesystem even if we are testing format lifecycle
• small docs addition
• changeset
• squashed commits, adjusted commit msg

Thanks for contributing!

[Razinsky]

Excellent 👌 Thanks @jorenbroekema ! It's great to see your additions, this will be helpful for my next contribution ;)

Quick question: what is your stance regarding the use of the options object? I was under the impression that this was the right way to go when it comes to adding custom "options" to our Style Dictionary config. I see that you pull the new variable out to be at the same level as the rest of the config.

[jorenbroekema]

Ah now that you mention it, it should probably be this:

transform: (token, platform) => checkAndEvaluateMath(token, platform.mathFractionDigits),

The current code also happens to work because platform options tend to be put on the config.options object, but it's not exactly its intention to use it like that, if readonly props were a thing in javascript then this would be one.

[jorenbroekema]

#295 fixing it here

[adamstankiewicz]

[question/clarification] I'm curious the rationale for exposing mathFractionDigits from within the Style Dictionary platforms config directly versus in the TransformOptions passed to register when registering the sd-transforms onto StyleDictionary, e.g.:

register(StyleDictionary, {
  platform: 'css',
  mathFractionDigits: 3,
});

The higher-level question is:

Where should options for sd-transforms get passed (Style Dictionary configuration vs. the TransformOptions passed during register)?

See this proposed PR for more context/details on the question; would appreciate your input/feedback. Thanks!

[jorenbroekema]

The answer depends on whether you want to register the option on a global level, then inside the register() function options 2nd param is appropriate, but in this case, it's a "transform" specific option, and transforms are always scoped by the platform, so I feel like putting the option in the platform config is more appropriate.

Generally speaking, there is no API for passing options to transforms, the workaround for that lack of feature has always been to set options for transforms on the platform config layer. We'd need to break the API around transforms to make this more intuitive, and we didn't really get to that for the v4. I think we may also need to document this "workaround" a bit better, because it's a bit tricky for folks to figure out that transforms get the platform config passed in the transform function, and that this is how you configure transform options.

[jorenbroekema]

amzn/style-dictionary#1298 this issue may be related btw.

Sometimes the current SD config API is a bit awkward, because certain transforms such as the math resolver transform, can be considered "global" in the sense that they would always be applied to all platforms, meaning you're duplicating some of the stuff in your SD config for each platform, and the same thing happens to the transform options, you have to apply it to each platform.
This is a bit annoying, and in the related issue in the SD repo I try to brainstorm a bit how we can re-architecture some of the SD config API to make a distinction between global transforms vs file-format related formatting transforms (e.g. not changing the value of the token, just formatting it slightly different e.g. rgb(r,g,b) -> UIColor(r,g,b).

So even though registering the math minimal fraction digits may seem a lot cleaner and less awkward to put on the register() call and thus global level, it stops people from changing the digits amount on a per platform basis (even though that seems like an unnecessary "feature"), and the awkwardness is something that SD should solve imo and not necessarily sd-transforms package. If that makes sense.

What I do if I have many platforms, much of which is duplicate/overlapping stuff:

const basePlatform = {
  mathFractionDigits: 3,
}

const sd = new StyleDictionary({
  platforms: {
    css: {
      ...basePlatform,
    },
    ios: {
      ...basePlatform,
    }
  }
})