feat: pass ref path in getReferences util output (#1226)

Author: jorenbroekema

.changeset/spotty-sheep-mix.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Pass the original ref path to the `getReferences` util result tokens.

__tests__/utils/reference/getReferences.test.js

@@ -62,24 +62,28 @@ describe('utils', () => {
       });
 
       it(`should work with a single reference`, () => {
-        expect(_getReferences(tokens.color.danger.value, tokens)).to.eql([{ value: '#f00' }]);
+        expect(_getReferences(tokens.color.danger.value, tokens)).to.eql([
+          { ref: ['color', 'red'], value: '#f00' },
+        ]);
       });
 
       it(`should work with object values`, () => {
         expect(_getReferences(tokens.border.primary.value, tokens)).to.eql([
-          { value: '#f00' },
-          { value: '2px' },
+          { ref: ['color', 'red'], value: '#f00' },
+          { ref: ['size', 'border'], value: '2px' },
         ]);
       });
 
       it(`should work with objects that have numbers`, () => {
-        expect(_getReferences(tokens.border.secondary.value, tokens)).to.eql([{ value: '#f00' }]);
+        expect(_getReferences(tokens.border.secondary.value, tokens)).to.eql([
+          { ref: ['color', 'red'], value: '#f00' },
+        ]);
       });
 
       it(`should work with interpolated values`, () => {
         expect(_getReferences(tokens.border.tertiary.value, tokens)).to.eql([
-          { value: '2px' },
-          { value: '#f00' },
+          { ref: ['size', 'border'], value: '2px' },
+          { ref: ['color', 'red'], value: '#f00' },
         ]);
       });
     });

docs/src/content/docs/reference/Hooks/preprocessors.md

@@ -21,12 +21,12 @@ That said, preprocessing the full dictionary gives ultimate flexibility when nee
 A preprocessor is an object with two props:
 
 - `name`: the name of the preprocessor
-- `preprocessor` a callback function that receives the dictionary as a parameter, and returns the processed dictionary
+- `preprocessor` a callback function that receives the dictionary and SD options as parameters, and returns the processed dictionary
 
 ```javascript title="my-preprocessor.js"
 const myPreprocessor = {
   name: 'strip-third-party-meta',
-  preprocessor: (dictionary) => {
+  preprocessor: (dictionary, options) => {
     delete dictionary.thirdPartyMetadata;
     return dictionary;
   },
@@ -38,7 +38,7 @@ Asynchronous callback functions are also supported, giving even more flexibility
 ```javascript title="my-preprocessor-async.js"
 const myPreprocessor = {
   name: 'strip-props',
-  preprocessor: async (dictionary) => {
+  preprocessor: async (dictionary, options) => {
     const propsToDelete = await someAPICall();
 
     propsToDelete.forEach((propName) => {
@@ -112,7 +112,7 @@ Stripping description property recursively in the entire dictionary object:
 ```js
 StyleDictionary.registerPreprocessor({
   name: 'strip-descriptions',
-  preprocessor: (dict) => {
+  preprocessor: (dict, options) => {
     // recursively traverse token objects and delete description props
     function removeDescription(slice) {
       delete slice.description;

docs/src/content/docs/reference/Utils/references.md

@@ -91,8 +91,8 @@ getReferences('solid {spacing.2} {colors.black}', sd.tokens); // alternative way
 getReferences('solid {spacing.2} {colors.black}', sd.tokens, { usesDtcg: true }); // Assumes DTCG spec format, with $ prefix ($value, $type)
 /**
  * [
- *   { value: '2px', type: 'dimension' },
- *   { value: '#000', type: 'color' }
+ *   { value: '2px', type: 'dimension', ref: ['spacing', '2'] },
+ *   { value: '#000', type: 'color', ref: ['colors', 'black'] }
  * ]
  */
 ```

lib/utils/references/getReferences.js

@@ -88,7 +88,7 @@ export function _getReferences(
     }
 
     if (ref !== undefined) {
-      references.push(ref);
+      references.push({ ...ref, ref: pathName });
     } else if (throwImmediately) {
       throw new Error(`tries to reference ${variable}, which is not defined.`);
     }