Align Hooks APIs (#1185)

* feat: move fileHeader global prop to hooks.fileHeaders (#1177)

* feat: move filter global prop to hooks.filters, rename matcher to filter (#1179)

* feat: move action global prop to hooks.actions (#1180)

* feat: move parsers global prop to hooks.parsers, apply explicitly (#1181)

* feat: move transformGroup global prop to hooks.transformGroups (#1182)

Co-authored-by: Joren Broekema <[email protected]>

* feat: move transforms global prop to hooks.transforms, align api (#1183)

* feat: move formats global prop to hooks.formats, align api (#1184)

---------

Co-authored-by: Joren Broekema <[email protected]>

.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/large-peaches-fetch.md

@@ -0,0 +1,34 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Actions, when registered, are put inside the `hooks.actions` property now, as opposed to `action`.
+Note the change from singular to plural form here.
+
+Before:
+
+```js
+export default {
+  action: {
+    'copy-assets': {
+      do: () => {}
+      undo: () => {}
+    }
+  },
+};
+```
+
+After:
+
+```js
+export default {
+  hooks: {
+    actions: {
+      'copy-assets': {
+        do: () => {}
+        undo: () => {}
+      }
+    },
+  },
+};
+```

.changeset/old-nails-hammer.md

@@ -0,0 +1,72 @@
+---
+'style-dictionary': major
+---
+
+Filters, when registered, are put inside the `hooks.filters` property now, as opposed to `filter`.
+Note the change from singular to plural form here.
+
+Before:
+
+```js
+export default {
+  filter: {
+    'colors-only': (token) => token.type === 'color,
+  },
+  platforms: {
+    css: {
+      files: [{
+        format: 'css/variables',
+        destination: '_variables.css',
+        filter: 'colors-only',
+      }],
+    },
+  },
+};
+```
+
+After:
+
+```js
+export default { 
+  hooks: {
+    filters: {
+      'colors-only': (token) => token.type === 'color,
+    },
+  },
+  platforms: {
+    css: {
+      files: [{
+        format: 'css/variables',
+        destination: '_variables.css',
+        filter: 'colors-only',
+      }],
+    },
+  },
+};
+```
+
+In addition, when using [`registerFilter`](/reference/api#registerfilter) method, the name of the filter function is now `filter` instead of `matcher`.
+
+Before:
+
+```js title="build-tokens.js" del={5} ins={6}
+import StyleDictionary from 'style-dictionary';
+
+StyleDictionary.registerFilter({
+  name: 'colors-only',
+  matcher: (token) => token.type === 'color',
+})
+```
+
+After:
+
+```js title="build-tokens.js" del={5} ins={6}
+import StyleDictionary from 'style-dictionary';
+
+StyleDictionary.registerFilter({
+  name: 'colors-only',
+  filter: (token) => token.type === 'color',
+})
+```
+
+> These changes also apply for the `filter` function (previously `matcher`) inside `transforms`.

.changeset/poor-parents-cover.md

@@ -0,0 +1,28 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Transform groups, when registered, are put inside the `hooks.transformGroups` property now, as opposed to `transformGroup`.
+
+Before:
+
+```js
+export default {
+  // register it inline or by SD.registerTransformGroup
+  transformGroup: {
+    foo: ['foo-transform']
+  },
+};
+```
+
+After:
+
+```js
+export default {
+  hooks: {
+    transformGroups: {
+      foo: ['foo-transform']
+    },
+  },
+};
+```

.changeset/seven-candles-smile.md

@@ -0,0 +1,67 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Formats, when registered, are put inside the `hooks.formats` property now, as opposed to `format`.
+The `formatter` handler function has been renamed to `format` for consistency.
+
+The importable type interfaces have also been renamed, `Formatter` is now `FormatFn` and `FormatterArguments` is now `FormatFnArguments`.
+Note that you can also use `Format['format']` instead of `FormatFn`, or `Parameters<Format['format']>` instead of `FormatFnArguments`, so these renames may not matter.
+
+Before:
+
+```ts
+import StyleDictionary from 'style-dictionary';
+import type { Formatter, FormatterArguments } from 'style-dictionary/types';
+
+// register it with register method
+StyleDictionary.registerFormat({
+  name: 'custom/json',
+  formatter: ({ dictionary }) => JSON.stringify(dictionary, 2, null),
+})
+
+export default {
+  // OR define it inline
+  format: {
+    'custom/json': ({ dictionary }) => JSON.stringify(dictionary, 2, null),
+  },
+  platforms: {
+    json: {
+      files: [{
+        destination: 'output.json',
+        format: 'custom/json'
+      }],
+    },
+  },
+};
+```
+
+After:
+
+```ts
+import StyleDictionary from 'style-dictionary';
+import type { FormatFn, FormatFnArguments } from 'style-dictionary/types';
+
+// register it with register method
+StyleDictionary.registerFormat({
+  name: 'custom/json',
+  format: ({ dictionary }) => JSON.stringify(dictionary, 2, null),
+})
+
+export default {
+  // OR define it inline
+  hooks: {
+    formats: {
+      'custom/json': ({ dictionary }) => JSON.stringify(dictionary, 2, null),
+    },
+  },
+  platforms: {
+    json: {
+      files: [{
+        destination: 'output.json',
+        format: 'custom/json'
+      }],
+    },
+  },
+};
+```

.changeset/smooth-jobs-attack.md

@@ -2,7 +2,7 @@
 'style-dictionary': major
 ---
 
-BREAKING: `className`, `packageName`, `mapName` and `type` options for a bunch of built-in formats have been moved from `file` to go inside the `file.options` object, for API consistency reasons.
+BREAKING: `className`, `packageName`, `mapName`, `type`, `name`, `resourceType` and `resourceMap` options for a bunch of built-in formats have been moved from `file` to go inside the `file.options` object, for API consistency reasons.
 
 Before:
 

.changeset/spicy-pears-work.md

@@ -0,0 +1,50 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Transforms, when registered, are put inside the `hooks.transforms` property now, as opposed to `transform`.
+The `matcher` property has been renamed to `filter` (to align with the Filter hook change), and the `transformer` handler function has been renamed to `transform` for consistency.
+
+Before:
+
+```js
+export default {
+  // register it inline or by SD.registerTransform
+  transform: {
+    'color-transform': {
+      type: 'value',
+      matcher: (token) => token.type === 'color',
+      transformer: (token) => token.value,
+    },
+  },
+  platforms: {
+    css: {
+      // apply it per platform
+      transforms: ['color-transform'],
+    },
+  },
+};
+```
+
+After
+
+```js
+export default {
+  // register it inline or by SD.registerTransform
+  hooks: {
+    transforms: {
+      'color-transform': {
+        type: 'value',
+        filter: (token) => token.type === 'color',
+        transform: (token) => token.value,
+      },
+    },
+  },
+  platforms: {
+    css: {
+      // apply it per platform
+      transforms: ['color-transform'],
+    },
+  },
+};
+```

.changeset/wet-sloths-taste.md

@@ -0,0 +1,41 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Parsers, when registered, are put inside the `hooks.parsers` property now, as opposed to `parsers`.
+`parsers` property has been repurposed: you will now also need to explicitly apply registered parsers by name in the `parsers` property, they no longer apply by default.
+When registering a parser, you must also supply a `name` property just like with all other hooks, and the `parse` function has been renamed to `parser` for consistency.
+
+Before:
+
+```js
+export default {
+  // register it inline or by SD.registerPreprocessor
+  parsers: [
+    {
+      pattern: /\.json5$/,
+      parse: ({ contents, filePath}) => {
+        return JSON5.parse(contents);
+      },
+    }
+  ],
+};
+```
+
+After:
+
+```js
+export default {
+  hooks: {
+    parsers: {
+      name: 'json5-parser',
+      pattern: /\.json5$/,
+      parser: ({ contents, filePath}) => {
+        return JSON5.parse(contents);
+      },
+    }
+  },
+  // apply it globally by name reference
+  parsers: ['json5-parser'],
+};
+```

.github/workflows/verify.yml

@@ -38,4 +38,4 @@ jobs:
         run: npx playwright install --with-deps chromium
 
       - name: Browser tests
-        run: npm run test:browser
+        run: npm run test

CONTRIBUTING.md

@@ -31,7 +31,7 @@ We use ESLint on the code to ensure a consistent style. Any new code committed m
 
 ### Code Rules
 
-1. **Do not mutate token names or values in a format.** Mutations like this should happen in a transformer.
+1. **Do not mutate token names or values in a format.** Mutations like this should happen in a transform.
 1. **Be as generic as possible.** Do not hard-code any values or configuration in formats.
 1. **Fail loudly.** Users should be aware if something is missing or configurations aren't correct. This will help debug any issues instead of failing silently.
 1. **Rely on few dependencies.** This framework is meant to be extended and allows for customization. We don't want to bring a slew of dependencies that most people don't need.

README.md

@@ -302,10 +302,10 @@ const StyleDictionary = require('style-dictionary').extend('config.json');
 StyleDictionary.registerTransform({
   name: 'time/seconds',
   type: 'value',
-  matcher: function (token) {
+  filter: function (token) {
     return token.type === 'time';
   },
-  transformer: function (token) {
+  transform: function (token) {
     return (parseInt(token.original.value) / 1000).toString() + 's';
   },
 });