chore(typescript): migrating to typescript

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/angry-balloons-yell.md

@@ -0,0 +1,20 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: 
+- `usesReference` util function is now `usesReferences` to be consistent plural form like the other reference util functions.
+- `getReferences` first and second parameters have been swapped to be consistent with `resolveReferences`, so value first, then the full token object (instead of the entire dictionary instance).
+- `getReferences` accepts a third options parameter which can be used to set reference Regex options as well as an unfilteredTokens object which can be used as a fallback when references are made to tokens that have been filtered out. There will be warnings logged for this.
+- `format.formatter` removed old function signature of `(dictionary, platform, file)` in favor of `({ dictionary, platform, options, file })`.
+- Types changes:
+
+  - Style Dictionary is entirely strictly typed now, and there will be `.d.ts` files published next to every file, this means that if you import from one of Style Dictionary's entrypoints, you automatically get the types implicitly with it. This is a big win for people using TypeScript, as the majority of the codebase now has much better types, with much fewer `any`s.
+  - There is no more hand-written Style Dictionary module `index.d.ts` anymore that exposes all type interfaces on itself. This means that you can no longer grab types that aren't members of the Style Dictionary class directly from the default export of the main entrypoint. External types such as `Parser`, `Transform`, `DesignTokens`, etc. can be imported from the newly added types entrypoint:
+
+  ```ts
+  import type { DesignTokens, Transform, Parser } from 'style-dictionary/types';
+  ```
+
+  Please raise an issue if you find anything missing or suddenly broken.
+  - `Matcher`, `Transformer`, `Formatter`, etc. are still available, although no longer directly but rather as properties on their parents, so `Filter['matcher']`, `Transform['transformer']`, `Format['formatter']`

.changeset/big-worms-collect-2.md

@@ -0,0 +1,12 @@
+---
+'style-dictionary': minor
+---
+
+FileSystem that is used by Style Dictionary can now be customized:
+
+```js
+import { setFs } from 'style-dictionary/fs';
+setFs(myFileSystemShim);
+```
+
+By default, it uses an in-memory filesystem shim `@bundled-es-modules/memfs` in browser context, `node:fs` built-in module in Node context.

.changeset/big-worms-collect.md

@@ -0,0 +1,10 @@
+---
+'style-dictionary': major
+---
+
+- The project has been fully converted to [ESM format](https://nodejs.org/api/esm.html), which is also the format that the browser uses.
+  For users, this means you'll have to either use Style Dictionary in ESM JavaScript code, or dynamically import it into your CommonJS code.
+- `StyleDictionary.extend()` method is now asynchronous, which means it returns `Promise<StyleDictionary.Core>` instead of `StyleDictionary.Core`.
+- `allProperties` / `properties` was deprecated in v3, and is now removed from `StyleDictionary.Core`, use `allTokens` and `tokens` instead.
+- Templates and the method `registerTemplate` were deprecated in v3, now removed. Use Formats instead.
+- The package now uses [package entrypoints](https://nodejs.org/api/packages.html), which means that what is importable from the package is locked down to just the specified entrypoints: `style-dictionary` & `style-dictionary/fs`. If more is needed, please raise an issue explaining which file you were importing and why you need it to be public API.

.changeset/bright-timers-shout.md

@@ -0,0 +1,11 @@
+---
+'style-dictionary': patch
+---
+
+Allow overriding CSS formatting with commentStyle and commentPosition props.
+For commentStyle, options are 'short' or 'long'.
+For commentPosition, options are 'above' or 'inline'.
+
+We also ensure that the right defaults are picked for CSS, SASS/SCSS, Stylus and Less.
+
+This also contains a fix for ensuring that multi-line comments are automatically put "above" rather than "inline".

.changeset/chilled-oranges-drive.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Fix some inconsistencies in some of the templates, usually with regards to spaces/newlines

.changeset/chilly-numbers-work.md

@@ -0,0 +1,23 @@
+---
+'style-dictionary': minor
+---
+
+Allow not throwing fatal errors on broken token references/aliases, but `console.error` instead.
+
+You can also configure this on global/platform `log` property:
+
+```json
+{
+  "log": {
+    "errors": {
+      "brokenReferences": "console"
+    }
+  }
+}
+```
+
+This setting defaults to `"error"` when not configured.
+
+`resolveReferences` and `getReferences` `warnImmediately` option is set to `true` which causes an error to be thrown/warned immediately by default, which can be configured to `false` if you know those utils are running in the transform/format hooks respectively, where the errors are collected and grouped, then thrown as 1 error/warning instead of multiple.
+
+Some minor grammatical improvements to some of the error logs were also done.

.changeset/chilly-worms-vanish.md

@@ -0,0 +1,27 @@
+---
+'style-dictionary': patch
+---
+
+All formats using `createPropertyFormatter` or `formattedVariables` helpers now respect the `file.options.formatting` option passed by users to customize formatting.
+
+Example:
+
+```js
+{
+  platforms: {
+    css: {
+      transformGroup: 'css',
+      buildPath,
+      files: [
+        {
+          destination: 'variables.css',
+          format: 'css/variables',
+          options: {
+            formatting: { indentation: '    ' },
+          },
+        },
+      ]
+    }
+  }
+}
+```

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "v4",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/cuddly-cheetahs-drum.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Rename `typeW3CDelegate` utility function to `typeDtcgDelegate`, as using "W3C" is highly discouraged when the standard isn't a W3C standard yet.

.changeset/curvy-geckos-exist.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Conditionally only run dev scripts when CWD is style-dictionary, so our consumers don't run it by accident

.changeset/eight-items-cheat.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Patch StyleDictionary main type file to export default instead of "export =" which does not work in ESM.

.changeset/eleven-llamas-raise.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix typeDtcgDelegate util $type property position to be allowed anywhere in the object, not just at the top.

.changeset/famous-falcons-join.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix outputReferences for DTCG spec tokens, by using token.original.$value instead of token.original.value.

.changeset/famous-suns-rule.md

@@ -0,0 +1,15 @@
+---
+'style-dictionary': minor
+---
+
+Added the following transforms for CSS, and added them to the `scss`, `css` and `less` transformGroups:
+
+- `fontFamily/css` -> wraps font names with spaces in `'` quotes
+- `cubicBezier/css` -> array value, put inside `cubic-bezier()` CSS function
+- `strokeStyle/css/shorthand` -> object value, transform to CSS shorthand
+- `border/css/shorthand` -> object value, transform to CSS shorthand
+- `typography/css/shorthand` -> object value, transform to CSS shorthand
+- `transition/css/shorthand` -> object value, transform to CSS shorthand
+- `shadow/css/shorthand` -> object value (or array of objects), transform to CSS shorthand
+
+The main intention here is to ensure that Style Dictionary is compliant with [DTCG draft specification](https://design-tokens.github.io/community-group/format/) out of the box with regards to exporting to CSS, where object-value tokens are not supported without transforming them to shorthands (or expanding them, which is a different feature that was added in `4.0.0-prerelease.27`).

.changeset/fifty-dragons-heal.md

@@ -0,0 +1,6 @@
+---
+'style-dictionary': minor
+---
+
+Preprocessors are a new feature added to style-dictionary, which allows you to do any type of processing of the token dictionary **after** parsing, **before** resolving and transforming.
+See [preprocessor docs](https://github.com/amzn/style-dictionary/tree/v4/docs/preprocessors.md) for more information.

.changeset/fifty-hats-study.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Expose flattenTokens utility.

.changeset/five-crews-hear.md

@@ -0,0 +1,36 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: File headers, when registered, are put inside the `hooks.fileHeaders` property now, as opposed to `fileHeader`.
+Note the change from singular to plural form here.
+
+Before:
+
+```js
+export default {
+  fileHeader: {
+    foo: (defaultMessages = []) => [
+      'Ola, planet!',
+      ...defaultMessages,
+      'Hello, World!'
+    ],
+  },
+}
+```
+
+After:
+
+```js
+export default {
+  hooks: {
+    fileHeaders: {
+      foo: (defaultMessages = []) => [
+        'Ola, planet!',
+        ...defaultMessages,
+        'Hello, World!'
+      ],
+    },
+  },
+}
+```

.changeset/five-kangaroos-destroy.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Re-add and update example basic, fix copySync command in CLI, fix android templates to use $type for DTCG tokens.

.changeset/four-fireants-try.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Pass outputReferenceFallbacks option to the relevant utilities, so the option actually works.

.changeset/fuzzy-gorillas-prove.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+'size/rem' transform to not transform tokens that already have a unit, such as `"4px"`, this should not be transformed to `"4rem"`.

.changeset/gold-countries-own.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix parsers async support, use resolved filePath instead of raw.

.changeset/gorgeous-lamps-chew.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+options.log to be respected in all error logging, including platform specific logs.

.changeset/great-trainers-shop.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Allow transitive transforms to return undefined, by doing this the transformer can mark itself as "deferred" for that specific token. This is useful when references in properties other than "value" need to be resolved first.

.changeset/green-wolves-heal.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Escape double quotes for ts outputStringLiterals

.changeset/grumpy-peaches-flow.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix small issue in type DTCG delegate utility type tracking.

.changeset/happy-glasses-teach.md

@@ -0,0 +1,43 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Logging has been redesigned a fair bit and is more configurable now.
+
+Before:
+
+```json
+{
+  "log": "error" // 'error' | 'warn'  -> 'warn' is the default value
+}
+```
+
+After:
+
+```json
+{
+  "log": {
+    "warnings": "error", // 'error' | 'warn'  -> 'warn' is the default value
+    "verbosity": "verbose" // 'default' | 'verbose' | 'silent'  -> 'default' is the default value
+  }
+}
+```
+
+Log is now and object and the old "log" option is now "warnings".
+
+This configures whether the following five warnings will be thrown as errors instead of being logged as warnings:
+
+- Token value collisions (in the source)
+- Token name collisions (when exporting)
+- Missing "undo" function for Actions
+- File not created because no tokens found, or all of them filtered out
+- Broken references in file when using outputReferences, but referring to a token that's been filtered out
+
+Verbosity configures whether the following warnings/errors should display in a verbose manner:
+
+- Token collisions of both types (value & name)
+- Broken references due to outputReferences & filters
+- Token reference errors
+
+And it also configures whether success/neutral logs should be logged at all.
+Using "silent" (or --silent in the CLI) means no logs are shown apart from fatal errors.

.changeset/happy-numbers-grab.md

@@ -0,0 +1,18 @@
+---
+'style-dictionary': minor
+---
+
+Expose a new utility called resolveReferences which takes a value containing references, the dictionary object, and resolves the value's references for you.
+
+```js
+import StyleDictionary from 'style-dictionary';
+import { resolveReferences } from 'style-dictionary/utils';
+
+const sd = new StyleDictionary({ tokens: {
+  foo: { value: 'foo' },
+  bar: { value: '{foo}' },
+  qux: { value: '{bar}' },
+}});
+
+console.log(resolveReferences(sd.tokens.qux.value, sd.tokens)); // 'foo'
+```

.changeset/happy-vans-end.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix a couple of spots where DTCG option wasn't properly taken into account, more tests added.

.changeset/hip-candles-flow.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Fix logging to be ordered by platform when building or cleaning platforms. This now happens in parallel, resulting in the logs being ordered randomly which was a small regression to the logging experience.

.changeset/honest-toes-wink.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Allow falsy token values for outputReferences, e.g. `0`.

.changeset/kind-rats-invite.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Improve and test the error handling of standalone usage of reference utilities.