From 182e96c03cc5bc810d9fdcde09459454225926d2 Mon Sep 17 00:00:00 2001
From: jorenbroekema <joren.broekema@gmail.com>
Date: Mon, 9 Dec 2024 12:17:52 +0100
Subject: [PATCH] chore: update docs for outputting refs in custom JS format

---
 .github/workflows/release.yml                 |  2 +-
 .../docs/reference/Hooks/Formats/index.md     | 31 +++++++++++++------
 package.json                                  |  3 +-
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 04b0d014d..76f8bee41 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -29,7 +29,7 @@ jobs:
           publish: npm run release
           commit: 'chore: release'
           # to ensure the lock file also gets bumped accordingly and added to the commit
-          version: 'npx changeset version && npm install'
+          version: 'npm run version'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/docs/src/content/docs/reference/Hooks/Formats/index.md b/docs/src/content/docs/reference/Hooks/Formats/index.md
index b0a38617f..4926e0bc8 100644
--- a/docs/src/content/docs/reference/Hooks/Formats/index.md
+++ b/docs/src/content/docs/reference/Hooks/Formats/index.md
@@ -378,26 +378,37 @@ To take advantage of outputting references in your custom formats there are 2 he
 ```javascript title="build-tokens.js"
 StyleDictionary.registerFormat({
   name: `es6WithReferences`,
-  format: function ({ dictionary }) {
+  format: function ({ dictionary, options }) {
+    const { usesDtcg, outputReferences } = options;
     return dictionary.allTokens
       .map((token) => {
         let value = JSON.stringify(token.value);
-        // the `dictionary` object now has `usesReference()` and
-        // `getReferences()` methods. `usesReference()` will return true if
+        const originalValue = token.original.value;
+        // the `dictionary` object now has `usesReferences()` and
+        // `getReferences()` methods. `usesReferences()` will return true if
         // the value has a reference in it. `getReferences()` will return
         // an array of references to the whole tokens so that you can access their
         // names or any other attributes.
-        if (dictionary.usesReference(token.original.value)) {
-          // Note: make sure to use `token.original.value` because
+        const shouldOutputRef =
+          usesReferences(originalValue) &&
+          (typeof outputReferences === 'function'
+            ? outputReferences(token, { dictionary, usesDtcg })
+            : outputReferences);
+
+        if (shouldOutputRef) {
+          // Note: make sure to use `originalValue` because
           // `token.value` is already resolved at this point.
-          const refs = dictionary.getReferences(token.original.value);
+          const refs = dictionary.getReferences(originalValue);
+          let isEntirelyRef = refs.length === 1 && refs[0].value === value;
           refs.forEach((ref) => {
-            value = value.replace(ref.value, function () {
-              return `${ref.name}`;
-            });
+            // wrap in template literal ${} braces if the value is more than just entirely a reference
+            value = value.replace(ref.value, isEntirelyRef ? ref.name : `\${${ref.name}}`);
           });
         }
-        return `export const ${token.name} = ${value};`;
+        // if the value is not entirely a reference, we have to wrap in template literals
+        return `export const ${token.name} = ${
+          shouldOutputRef && !isEntirelyRef ? `\`${value}\`` : value
+        };`;
       })
       .join(`\n`);
   },
diff --git a/package.json b/package.json
index 5aef0f706..bd137835f 100644
--- a/package.json
+++ b/package.json
@@ -64,7 +64,8 @@
     "install-cli": "npm install -g $(npm pack)",
     "release": "npm run build && changeset publish",
     "prepare": "husky install",
-    "postinstall": "patch-package"
+    "postinstall": "patch-package",
+    "version": "changeset version && npm install"
   },
   "lint-staged": {
     "*.js": [