style-dictionary 5.1.3 → 5.2.0

package/examples/advanced/assets-base64-embed/package.json

@@ -12,6 +12,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/create-react-app/package.json

@@ -12,7 +12,7 @@
   },
   "devDependencies": {
     "eslint-config-react-app": "^7.0.1",
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   },
   "resolutions": {
     "immer": "8.0.1",

package/examples/advanced/create-react-native-app/package.json

@@ -29,7 +29,7 @@
     "eslint-config-react-app": "^7.0.1",
     "jest": "~25.2.6",
     "react-test-renderer": "~16.13.1",
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   },
   "jest": {
     "preset": "react-native"

package/examples/advanced/custom-parser/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/custom-transforms/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/font-face-rules/package.json

@@ -9,6 +9,6 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/format-helpers/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/matching-build-files/package.json

@@ -17,6 +17,6 @@
   "author": "Kelly Harrop <kn.harrop@gmail.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/multi-brand-multi-platform/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/node-modules-as-config-and-properties/package.json

@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/dbanksdesign/style-dictionary-node#readme",
   "devDependencies": {
-    "style-dictionary": "^5.1.3",
+    "style-dictionary": "^5.2.0",
     "tinycolor2": "^1.4.1"
   }
 }

package/examples/advanced/npm-module/package.json

@@ -17,6 +17,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/referencing_aliasing/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/s3/package.json

@@ -16,6 +16,6 @@
   "devDependencies": {
     "aws-sdk": "^2.7.21",
     "fs-extra": "^1.0.0",
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/tailwind-preset/package.json

@@ -10,7 +10,7 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3",
+    "style-dictionary": "^5.2.0",
     "tailwindcss": "^3.4.15",
     "mocha": "^10.2.0",
     "chai": "^5.1.1"

package/examples/advanced/tokens-deprecation/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/transitive-transforms/package.json

@@ -12,6 +12,6 @@
   "license": "ISC",
   "devDependencies": {
     "colorjs.io": "^0.5.2",
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/variables-in-outputs/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "style-dictionary": "^5.1.3"
+    "style-dictionary": "^5.2.0"
   }
 }

package/examples/advanced/yaml-tokens/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.3",
+    "style-dictionary": "^5.2.0",
     "yaml": "^1.10.0"
   }
 }

package/lib/StyleDictionary.js

@@ -67,7 +67,7 @@ export default class StyleDictionary extends Register {
   // Placeholder is transformed on prepublish -> see scripts/inject-version.js
   // Another option might be import pkg from './package.json' with { "type": "json" } which would work in both browser and node, but support is not there yet.
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#browser_compatibility
-  static VERSION = '5.1.3';
+  static VERSION = '5.2.0';
 
   /** @returns {Config} */
   get options() {

package/lib/common/formatHelpers/fileHeader.js

@@ -61,11 +61,15 @@ export default async function fileHeader({ file, commentStyle, formatting = {},
     fn = file.options.fileHeader;
   }
 
-  let { prefix, lineSeparator, header, footer, fileHeaderTimestamp } = Object.assign(
-    {},
-    defaultFormatting,
-    formatting,
-  );
+  let {
+    prefix,
+    lineSeparator,
+    header,
+    commentStyle: _commentStyle,
+    footer,
+    fileHeaderTimestamp,
+  } = Object.assign({}, defaultFormatting, formatting);
+  const commentStyleMerged = commentStyle ?? _commentStyle;
 
   // default header
   const defaultHeader = [
@@ -73,11 +77,11 @@ export default async function fileHeader({ file, commentStyle, formatting = {},
     ...(fileHeaderTimestamp ? [`Generated on ${new Date().toUTCString()}`] : []),
   ];
 
-  if (commentStyle === commentStyles.short) {
+  if (commentStyleMerged === commentStyles.short) {
     prefix = `// `;
     header = `${lineSeparator}`;
     footer = `${lineSeparator}${lineSeparator}`;
-  } else if (commentStyle === 'xml') {
+  } else if (commentStyleMerged === 'xml') {
     prefix = `  `;
     header = `<!--${lineSeparator}`;
     footer = `${lineSeparator}-->`;

package/lib/common/formatHelpers/formattedVariables.d.ts

@@ -11,6 +11,7 @@
  * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. This will get passed to `formatHelpers` -> `createPropertyformat` and used for the `lineSeparator` between lines of code.
  * @param {Boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
+ * @param {SortOption} [options.sort] - Optional sorting strategy.
  * @returns {String}
  * @example
  * ```js
@@ -28,7 +29,7 @@
  * });
  * ```
  */
-export default function formattedVariables({ format, dictionary, outputReferences, outputReferenceFallbacks, formatting, themeable, usesDtcg, }: {
+export default function formattedVariables({ format, dictionary, outputReferences, outputReferenceFallbacks, formatting, themeable, usesDtcg, sort, }: {
     format: string;
     dictionary: Dictionary;
     outputReferences?: import("../../../types/Format.d.ts").OutputReferences | undefined;
@@ -36,9 +37,12 @@ export default function formattedVariables({ format, dictionary, outputReference
     formatting?: import("../../../types/File.d.ts").FormattingOptions | undefined;
     themeable?: boolean | undefined;
     usesDtcg?: boolean | undefined;
+    sort?: import("../../../types/Sort.d.ts").SortOption | undefined;
 }): string;
 export type Token = import("../../../types/DesignToken.d.ts").TransformedToken;
 export type Tokens = import("../../../types/DesignToken.d.ts").TransformedTokens;
 export type Formatting = import("../../../types/File.d.ts").FormattingOptions;
 export type OutputReferences = import("../../../types/Format.d.ts").OutputReferences;
+export type SortFn = import("../../../types/Sort.d.ts").SortFn;
+export type SortOption = import("../../../types/Sort.d.ts").SortOption;
 export type Dictionary = import("../../../types/DesignToken.d.ts").Dictionary;

package/lib/common/formatHelpers/formattedVariables.js

@@ -1,11 +1,14 @@
 import createPropertyFormatter from './createPropertyFormatter.js';
 import sortByReference from './sortByReference.js';
+import sortByName from './sortByName.js';
 
 /**
  * @typedef {import('../../../types/DesignToken.d.ts').TransformedToken} Token
  * @typedef {import('../../../types/DesignToken.d.ts').TransformedTokens} Tokens
  * @typedef {import('../../../types/File.d.ts').FormattingOptions} Formatting
  * @typedef {import('../../../types/Format.d.ts').OutputReferences} OutputReferences
+ * @typedef {import('../../../types/Sort.d.ts').SortFn} SortFn
+ * @typedef {import('../../../types/Sort.d.ts').SortOption} SortOption
  * @typedef {import('../../../types/DesignToken.d.ts').Dictionary} Dictionary
  */
 
@@ -26,6 +29,7 @@ const defaultFormatting = {
  * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. This will get passed to `formatHelpers` -> `createPropertyformat` and used for the `lineSeparator` between lines of code.
  * @param {Boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
+ * @param {SortOption} [options.sort] - Optional sorting strategy.
  * @returns {String}
  * @example
  * ```js
@@ -51,6 +55,7 @@ export default function formattedVariables({
   formatting = {},
   themeable = false,
   usesDtcg = false,
+  sort,
 }) {
   // typecast, we know that by know the tokens have been transformed
   let allTokens = /** @type {Token[]} */ (dictionary.allTokens);
@@ -59,18 +64,62 @@ export default function formattedVariables({
 
   let { lineSeparator } = Object.assign({}, defaultFormatting, formatting);
 
-  // Some languages are imperative, meaning a variable has to be defined
-  // before it is used. If `outputReferences` is true, check if the token
-  // has a reference, and if it does send it to the end of the array.
-  // We also need to account for nested references, a -> b -> c. They
-  // need to be defined in reverse order: c, b, a so that the reference always
-  // comes after the definition
-  if (outputReferences) {
+  const sortInputs = sort ? (Array.isArray(sort) ? sort : [sort]) : [];
+
+  // reference-safety sorter is an internal concern:
+  // we only compute it when outputReferences=true
+  const byReference = outputReferences
+    ? sortByReference(tokens, { unfilteredTokens: dictionary.unfilteredTokens, usesDtcg })
+    : null;
+
+  /**
+   * @param {SortFn} keyOrFn
+   * @returns {((a: Token, b: Token) => number) | null}
+   */
+  const normalize = (keyOrFn) => {
+    if (typeof keyOrFn === 'function') return keyOrFn;
+
+    if (keyOrFn === 'name') return sortByName;
+
+    // Fail loudly for invalid values (esp. typos)
+    if (typeof keyOrFn === 'string') {
+      throw new Error(
+        `Invalid "sort" option: "${keyOrFn}". ` +
+          `Use "name", a comparator function, or an array of those.`,
+      );
+    }
+
+    // Non-string non-function values are also invalid
+    throw new Error(
+      `Invalid "sort" option type: ${typeof keyOrFn}. ` +
+        `Use "name", a comparator function, or an array of those.`,
+    );
+  };
+
+  /**
+   * @param {((a: Token, b: Token) => number) | null} s
+   * @returns {s is ((a: Token, b: Token) => number)}
+   */
+  const isComparator = (s) => s !== null;
+
+  const requestedSorters = sortInputs.map(normalize).filter(isComparator);
+
+  // If outputReferences=true, enforce reference-safe ordering first (define-before-use safety).
+  // The user-provided sort acts as a tie-breaker on top.
+  const comparators = outputReferences
+    ? [byReference, ...requestedSorters].filter(isComparator)
+    : requestedSorters.filter(isComparator);
+
+  if (comparators.length > 0) {
     // note: using the spread operator here so we get a new array rather than
     // mutating the original
-    allTokens = [...allTokens].sort(
-      sortByReference(tokens, { unfilteredTokens: dictionary.unfilteredTokens, usesDtcg }),
-    );
+    allTokens = [...allTokens].sort((a, b) => {
+      for (const cmp of comparators) {
+        const r = cmp(a, b);
+        if (r !== 0) return r;
+      }
+      return 0;
+    });
   }
 
   return allTokens

package/lib/common/formats.js

@@ -193,7 +193,7 @@ const formats = {
       : options.selector
         ? [options.selector]
         : [`:root`];
-    const { outputReferences, outputReferenceFallbacks, usesDtcg, formatting } = options;
+    const { outputReferences, outputReferenceFallbacks, usesDtcg, formatting, sort } = options;
     const header = await fileHeader({
       file,
       formatting: getFormattingCloneWithoutPrefix(formatting),
@@ -219,6 +219,7 @@ const formats = {
         indentation: indentation.repeat(selector.length),
       },
       usesDtcg,
+      sort,
     });
 
     return (
@@ -289,7 +290,7 @@ const formats = {
    */
   [scssMapDeep]: async function ({ dictionary, options, file }) {
     // Default the "themeable" option to true for backward compatibility.
-    const { outputReferences, themeable = true, formatting, usesDtcg } = options;
+    const { outputReferences, themeable = true, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: long,
@@ -306,6 +307,7 @@ const formats = {
         themeable,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n' +
       scssMapDeepTemplate({ dictionary, options })
@@ -326,7 +328,7 @@ const formats = {
    * ```
    */
   [scssVariables]: async function ({ dictionary, options, file }) {
-    const { outputReferences, themeable = false, formatting, usesDtcg } = options;
+    const { outputReferences, themeable = false, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: short,
@@ -342,6 +344,7 @@ const formats = {
         themeable,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );
@@ -381,7 +384,7 @@ const formats = {
    * ```
    */
   [lessVariables]: async function ({ dictionary, options, file }) {
-    const { outputReferences, formatting, usesDtcg } = options;
+    const { outputReferences, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: short,
@@ -396,6 +399,7 @@ const formats = {
         outputReferences,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );
@@ -435,7 +439,7 @@ const formats = {
    * ```
    */
   [stylusVariables]: async function ({ dictionary, options, file, platform }) {
-    const { formatting, usesDtcg } = options;
+    const { formatting, usesDtcg, sort } = options;
     const outputReferences = !!platform.options?.outputReferences;
     const header = await fileHeader({
       file,
@@ -451,6 +455,7 @@ const formats = {
         outputReferences,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );

package/lib/common/transforms.js

@@ -105,7 +105,9 @@ function wrapValueWithDoubleQuote(token, options) {
  * @returns {string}
  */
 function throwSizeError(name, value, unitType) {
-  throw `Invalid Number: '${name}: ${value}' is not a valid number, cannot transform to '${unitType}' \n`;
+  throw new Error(
+    `Invalid Number: '${name}: ${value}' is not a valid number, cannot transform to '${unitType}' \n`,
+  );
 }
 
 /**

package/lib/enums/index.d.ts

@@ -1,12 +1,13 @@
 export { actions } from "./actions.js";
-export { logWarningLevels } from "./logWarningLevels.js";
-export { logVerbosityLevels } from "./logVerbosityLevels.js";
-export { logBrokenReferenceLevels } from "./logBrokenReferenceLevels.js";
-export { commentStyles } from "./commentStyles.js";
 export { commentPositions } from "./commentPositions.js";
+export { commentStyles } from "./commentStyles.js";
 export { fileHeaderCommentStyles } from "./fileHeaderCommentStyles.js";
 export { formats } from "./formats.js";
+export { logBrokenReferenceLevels } from "./logBrokenReferenceLevels.js";
+export { logVerbosityLevels } from "./logVerbosityLevels.js";
+export { logWarningLevels } from "./logWarningLevels.js";
+export { propertyFormatNames } from "./propertyFormatNames.js";
+export { builtInSorts } from "./sorts.js";
 export { transformGroups } from "./transformGroups.js";
 export { transforms } from "./transforms.js";
 export { transformTypes } from "./transformTypes.js";
-export { propertyFormatNames } from "./propertyFormatNames.js";

package/lib/enums/index.js

@@ -1,12 +1,13 @@
 export { actions } from './actions.js';
-export { logWarningLevels } from './logWarningLevels.js';
-export { logVerbosityLevels } from './logVerbosityLevels.js';
-export { logBrokenReferenceLevels } from './logBrokenReferenceLevels.js';
-export { commentStyles } from './commentStyles.js';
 export { commentPositions } from './commentPositions.js';
+export { commentStyles } from './commentStyles.js';
 export { fileHeaderCommentStyles } from './fileHeaderCommentStyles.js';
 export { formats } from './formats.js';
+export { logBrokenReferenceLevels } from './logBrokenReferenceLevels.js';
+export { logVerbosityLevels } from './logVerbosityLevels.js';
+export { logWarningLevels } from './logWarningLevels.js';
+export { propertyFormatNames } from './propertyFormatNames.js';
+export { builtInSorts } from './sorts.js';
 export { transformGroups } from './transformGroups.js';
 export { transforms } from './transforms.js';
 export { transformTypes } from './transformTypes.js';
-export { propertyFormatNames } from './propertyFormatNames.js';

package/lib/enums/sorts.d.ts

@@ -0,0 +1,3 @@
+export namespace builtInSorts {
+    let name: "name";
+}

package/lib/enums/sorts.js

@@ -0,0 +1,3 @@
+export const builtInSorts = {
+  name: /** @type {'name'} */ ('name'),
+};

package/lib/transform/token.js

@@ -46,20 +46,24 @@ async function _transformTokenWrapper(transform, token, config, options, vol) {
   try {
     to_ret = await transform.transform(token, config, options, vol);
   } catch (e) {
-    if (e instanceof Error) {
-      const transformError = createErrorMessage(token, e, transform.name, !!options?.usesDtcg);
-      // collect the errors so we can warn the user at the end of the run
-      GroupMessages.add(TRANSFORM_ERRORS, transformError);
+    const message = e instanceof Error ? e.message : String(e);
+    const transformError = createErrorMessage(
+      token,
+      e instanceof Error ? e : new Error(message),
+      transform.name,
+      !!options?.usesDtcg,
+    );
+    // collect the errors so we can warn the user at the end of the run
+    GroupMessages.add(TRANSFORM_ERRORS, transformError);
 
-      // Return a sensible fallback value
-      switch (transform.type) {
-        case 'attribute':
-          return token.attributes;
-        case 'name':
-          return token.name;
-        case 'value':
-          return options.usesDtcg ? token.$value : token.value;
-      }
+    // Return a sensible fallback value
+    switch (transform.type) {
+      case 'attribute':
+        return token.attributes;
+      case 'name':
+        return token.name;
+      case 'value':
+        return options.usesDtcg ? token.$value : token.value;
     }
   }
   return to_ret;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "5.1.3",
+  "version": "5.2.0",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",

package/types/Config.d.ts

@@ -5,6 +5,7 @@ import type { Parser } from './Parser.js';
 import type { Preprocessor } from './Preprocessor.js';
 import type { Transform } from './Transform.js';
 import type { Format, OutputReferences } from './Format.js';
+import type { SortOption } from './Sort.js';
 import type { Action } from './Action.js';
 import { logBrokenReferenceLevels, logWarningLevels, logVerbosityLevels } from '../lib/enums/index.js';
 type logWarningLevels = typeof logWarningLevels;
@@ -26,6 +27,7 @@ export interface LocalOptions {
     outputReferences?: OutputReferences;
     outputReferenceFallbacks?: boolean;
     formatting?: FormattingOverrides;
+    sort?: SortOption;
     [key: string]: any;
 }
 export interface GetReferencesOptions {

package/types/Sort.d.ts

@@ -0,0 +1,17 @@
+import type { TransformedToken } from './DesignToken.js';
+import { builtInSorts } from '../lib/enums/sorts.js';
+export type BuiltInSorts = typeof builtInSorts;
+export interface Sort {
+    name: string;
+    sort: SortFn;
+}
+/**
+ * A single sort function - either a built-in sort referenced by name string or a custom comparator function
+ * for inline usage
+ */
+export type SortFn = string | ((a: TransformedToken, b: TransformedToken) => number);
+/**
+ * Sort option for formattedVariables - can be a single sort item or an array of sort items
+ * (for chaining multiple sorts as tie-breakers)
+ */
+export type SortOption = SortFn | SortFn[];

package/types/index.d.ts

@@ -4,6 +4,7 @@ export type { DesignToken, DesignTokens, PreprocessedTokens, TransformedToken, T
 export type { FileHeader, File, FormattingOptions } from './File.js';
 export type { Filter } from './Filter.js';
 export type { Format, FormatFnArguments, FormatFn, OutputReferences } from './Format.js';
+export type { SortOption, SortFn, BuiltInSorts } from './Sort.js';
 export type { Parser, ParserOptions } from './Parser.js';
 export type { Preprocessor } from './Preprocessor.js';
 export type { Transform, NameTransform, AttributeTransform, ValueTransform } from './Transform.js';