feat: add convert to DTCG spec utilities, file converter docs site

.changeset/rare-toys-peel.md

@@ -0,0 +1,11 @@
+---
+'style-dictionary': minor
+---
+
+Add a couple of utilities for converting a regular Style Dictionary tokens object/file(s) to DTCG formatted tokens:
+
+- `convertToDTCG`
+- `convertJSONToDTCG`
+- `convertZIPToDTCG`
+
+[Documentation of these utilities](https://v4.styledictionary.com/reference/utils/dtcg/)

__tests__/__setup.js

@@ -4,6 +4,7 @@ import { dirname } from 'path-unified';
 import { fs } from 'style-dictionary/fs';
 import { chaiWtrSnapshot } from '../snapshot-plugin/chai-wtr-snapshot.js';
 import { fixDate } from './__helpers.js';
+import { writeZIP } from '../lib/utils/convertToDTCG.js';
 
 /**
  * We have a bunch of files that we use a mock data for our tests
@@ -17,24 +18,46 @@ import { fixDate } from './__helpers.js';
 
 fixDate();
 
-function ensureDirectoryExistence(filePath) {
+let hasInitializedResolve;
+export const hasInitialized = new Promise((resolve) => {
+  hasInitializedResolve = resolve;
+});
+// in case of Node env, we can resolve it immediately since we don't do this setup stuff
+if (typeof window !== 'object') {
+  hasInitializedResolve();
+}
+
+/**
+ * @param {string} filePath
+ */
+function ensureDirectoryExists(filePath) {
   const dir = dirname(filePath);
   if (fs.existsSync(dir)) {
     return true;
   }
   fs.mkdirSync(dir, { recursive: true });
 }
 
-function mirrorFile(file, contents) {
-  ensureDirectoryExistence(file);
-  fs.writeFileSync(file, contents, 'utf-8');
+/**
+ * @param {string} file
+ * @param {string | Record<string, string>} contents
+ */
+async function mirrorFile(file, contents) {
+  ensureDirectoryExists(file);
+  // zip files cannot just be written to FS using utf-8 encoding..
+  if (file.endsWith('.zip')) {
+    const zipResult = await writeZIP(contents);
+    contents = new Uint8Array(await zipResult.arrayBuffer());
+  }
+  await fs.promises.writeFile(file, contents);
 }
 
-export function setup(filesToMirror) {
+/**
+ * @param {[string, string | Record<string, string>][]} filesToMirror
+ */
+export async function setup(filesToMirror) {
   use(chaiAsPromised);
   use(chaiWtrSnapshot);
-
-  filesToMirror.forEach(([file, contents]) => {
-    mirrorFile(file, contents);
-  });
+  await Promise.all(filesToMirror.map(([file, contents]) => mirrorFile(file, contents)));
+  hasInitializedResolve();
 }