feat: allow configuring math fraction digits and color precision on different levels (WIP)

Author: Dario Soller

src/TransformOptions.ts

@@ -2,6 +2,8 @@ export type ColorModifierFormat = 'hex' | 'hsl' | 'lch' | 'p3' | 'srgb';
 
 export interface ColorModifierOptions {
   format: ColorModifierFormat;
+  mathFractionDigits?: number;
+  precision?: number;
 }
 
 export interface TransformOptions {

src/checkAndEvaluateMath.ts

@@ -2,9 +2,7 @@ import { DesignToken } from 'style-dictionary/types';
 import { Parser } from 'expr-eval-fork';
 import { parse, reduceExpression } from '@bundled-es-modules/postcss-calc-ast-parser';
 
-const defaultFractionDigits = 4;
 const mathChars = ['+', '-', '*', '/'];
-
 const parser = new Parser();
 
 function checkIfInsideGroup(expr: string, fullExpr: string): boolean {
@@ -75,10 +73,7 @@ function splitMultiIntoSingleValues(expr: string): string[] {
   return [expr];
 }
 
-export function parseAndReduce(
-  expr: string,
-  fractionDigits = defaultFractionDigits,
-): string | number {
+export function parseAndReduce(expr: string, mathFractionDigits: number): string | number {
   let result: string | number = expr;
 
   // Check if expression is already a number
@@ -149,14 +144,14 @@ export function parseAndReduce(
   }
 
   // the outer Number() gets rid of insignificant trailing zeros of decimal numbers
-  const reducedToFixed = Number(Number.parseFloat(`${result}`).toFixed(fractionDigits));
+  const reducedToFixed = Number(Number.parseFloat(`${result}`).toFixed(mathFractionDigits));
   result = resultUnit ? `${reducedToFixed}${resultUnit}` : reducedToFixed;
   return result;
 }
 
 export function checkAndEvaluateMath(
   token: DesignToken,
-  fractionDigits?: number,
+  mathFractionDigits: number,
 ): DesignToken['value'] {
   const expr = token.$value ?? token.value;
   const type = token.$type ?? token.type;
@@ -170,7 +165,7 @@ export function checkAndEvaluateMath(
       return expr;
     }
     const exprs = splitMultiIntoSingleValues(expr);
-    const reducedExprs = exprs.map(_expr => parseAndReduce(_expr, fractionDigits));
+    const reducedExprs = exprs.map(_expr => parseAndReduce(_expr, mathFractionDigits));
     if (reducedExprs.length === 1) {
       return reducedExprs[0];
     }

src/color-modifiers/mix.ts

@@ -6,8 +6,9 @@ export function mix(
   colorSpace: ColorSpaceTypes,
   amount: number,
   mixColor: Color,
+  precision: number,
 ): Color {
   const mixValue = Math.max(0, Math.min(1, Number(amount)));
 
-  return new Color(color.mix(mixColor, mixValue, { space: colorSpace }).toString());
+  return new Color(color.mix(mixColor, mixValue, { space: colorSpace }).toString({ precision }));
 }

src/color-modifiers/modifyColor.ts

@@ -37,10 +37,12 @@ export function modifyColor(
   }
 
   baseColor = parseUIColor(baseColor);
-
   const color = new Color(baseColor);
   let returnedColor = color;
-  const modifyValueResolvedCalc = Number(parseAndReduce(modifier.value, 4));
+  const modifyValueResolvedCalc = Number(
+    parseAndReduce(modifier.value, modifier.mathFractionDigits),
+  );
+
   try {
     switch (modifier.type) {
       case 'lighten':
@@ -55,6 +57,7 @@ export function modifyColor(
           modifier.space,
           modifyValueResolvedCalc,
           new Color(modifier.color),
+          modifier.precision,
         );
         break;
       case 'alpha': {
@@ -77,7 +80,11 @@ export function modifyColor(
       }
     }
 
-    return returnedColor.toString({ inGamut: true, precision: 3, format: modifier.format });
+    return returnedColor.toString({
+      inGamut: true,
+      precision: modifier.precision,
+      format: modifier.format,
+    });
   } catch (e) {
     return baseColor;
   }

src/color-modifiers/transformColorModifiers.ts

@@ -3,11 +3,17 @@ import { usesReferences } from 'style-dictionary/utils';
 import { modifyColor } from './modifyColor.js';
 import { ColorModifier } from '@tokens-studio/types';
 import { ColorModifierOptions } from '../TransformOptions.js';
+
+// 3 for backwards compatibility, but should better be 5, referring to the default precision (5) of the colorJS.io library
+// see: https://colorjs.io/docs/output.html#getting-a-string-representation-of-a-color
+const defaultColorPrecision = 3;
+
 /**
  * Helper: Transforms color tokens with tokens studio color modifiers
  */
 export function transformColorModifiers(
   token: DesignToken,
+  mathFractionDigits: number,
   options?: ColorModifierOptions,
 ): string | undefined {
   const modifier = token.$extensions['studio.tokens']?.modify as ColorModifier;
@@ -22,5 +28,11 @@ export function transformColorModifiers(
   if (options?.format) {
     modifier.format = options.format;
   }
+  if (!modifier.mathFractionDigits) {
+    modifier.mathFractionDigits = options?.mathFractionDigits ?? mathFractionDigits;
+  }
+  if (!modifier.precision) {
+    modifier.precision = options?.precision ?? defaultColorPrecision;
+  }
   return modifyColor(token.$value ?? token.value, modifier);
 }

src/register.ts

@@ -14,6 +14,8 @@ import { transformOpacity } from './transformOpacity.js';
 import { parseTokens } from './preprocessors/parse-tokens.js';
 import { transformShadow } from './css/transformShadow.js';
 
+const defaultFractionDigits = 4;
+
 export const getTransforms = (transformOpts?: TransformOptions) => {
   const agnosticTransforms = [
     'ts/descriptionToComment',
@@ -73,7 +75,8 @@ export async function register(sd: typeof StyleDictionary, transformOpts?: Trans
     type: 'value',
     transitive: true,
     filter: token => ['string', 'object'].includes(typeof (token.$value ?? token.value)),
-    transform: (token, platformCfg) => checkAndEvaluateMath(token, platformCfg.mathFractionDigits),
+    transform: (token, platformCfg) =>
+      checkAndEvaluateMath(token, platformCfg.mathFractionDigits ?? defaultFractionDigits),
   });
 
   sd.registerTransform({
@@ -171,7 +174,12 @@ export async function register(sd: typeof StyleDictionary, transformOpts?: Trans
       (token.$type ?? token.type) === 'color' &&
       token.$extensions &&
       token.$extensions['studio.tokens']?.modify,
-    transform: token => transformColorModifiers(token, transformOpts?.['ts/color/modifiers']),
+    transform: (token, platformCfg) =>
+      transformColorModifiers(
+        token,
+        platformCfg.mathFractionDigits ?? defaultFractionDigits,
+        transformOpts?.['ts/color/modifiers'],
+      ),
   });
 
   const includeBuiltinGroup = transformOpts?.withSDBuiltins ?? true;

test/integration/color-modifier-references.test.ts

@@ -88,15 +88,15 @@ describe('color modifier references', () => {
 
   it('supports color with referenced base color, referenced mix color and reference mix value', async () => {
     const file = await promises.readFile(outputFilePath, 'utf-8');
-    const content = excerpt(file, { start: new RegExp('--sdColor5: .*;'), end: '--sdColor8' });
-    const expectedOutput = `--sdColor7: #3b64b3;`;
+    const content = excerpt(file, { start: new RegExp('--sdColor6: .*;'), end: '--sdColor8' });
+    const expectedOutput = `--sdColor7: #32528c;`;
     expect(content).toBe(expectedOutput);
   });
 
   it('supports color with referenced base color, referenced mix color, and expression-based mix value with references', async () => {
     const file = await promises.readFile(outputFilePath, 'utf-8');
-    const content = excerpt(file, { start: new RegExp('--sdColor6: .*;'), end: '}' });
+    const content = excerpt(file, { start: new RegExp('--sdColor7: .*;'), end: '}' });
     const expectedOutput = `--sdColor8: #3b64b3;`;
-    expect(content).to.equal(expectedOutput);
+    expect(content).toBe(expectedOutput);
   });
 });