feat: move action global prop to hooks.actions

.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: () => {}
+      }
+    },
+  },
+};
+```

__tests__/register/action.test.js

@@ -20,7 +20,8 @@ registerSuite({
     undo: () => {},
   },
   registerMethod: 'registerAction',
-  prop: 'action',
+  prop: 'actions',
+  hooks: true,
 });
 
 describe('register', () => {
@@ -97,7 +98,7 @@ describe('register', () => {
         name: 'scss',
         do: function () {},
       });
-      expect(typeof StyleDictionaryExtended.action['scss'].do).to.equal('function');
+      expect(typeof StyleDictionaryExtended.hooks.actions['scss'].do).to.equal('function');
     });
 
     it('should handle an undo function', () => {
@@ -106,12 +107,12 @@ describe('register', () => {
         do: function () {},
         undo: function () {},
       });
-      expect(typeof StyleDictionaryExtended.action['scss'].undo).to.equal('function');
+      expect(typeof StyleDictionaryExtended.hooks.actions['scss'].undo).to.equal('function');
     });
 
     it('should properly pass the registered format to instances', async () => {
       const SDE2 = await StyleDictionaryExtended.extend({});
-      expect(typeof SDE2.action['scss'].do).to.equal('function');
+      expect(typeof SDE2.hooks.actions['scss'].do).to.equal('function');
     });
   });
 });

__tests__/transform/config.test.js

@@ -101,8 +101,10 @@ None of "barTransform", "bazTransform" match the name of a registered transform.
 
     it('warns the user if an action is used without a clean function', () => {
       const cfg = {
-        action: {
-          foo: {},
+        hooks: {
+          actions: {
+            foo: {},
+          },
         },
       };
       const platformCfg = {
@@ -121,8 +123,10 @@ None of "barTransform", "bazTransform" match the name of a registered transform.
     it('throws if an action is used without a clean function with log.warnings set to error', () => {
       const cfg = {
         log: { warnings: 'error' },
-        action: {
-          foo: {},
+        hooks: {
+          actions: {
+            foo: {},
+          },
         },
       };
       const platformCfg = {
@@ -137,8 +141,10 @@ None of "barTransform", "bazTransform" match the name of a registered transform.
     it('does not warn user at all when log.verbosity silent is used', () => {
       const cfg = {
         log: { verbosity: 'silent' },
-        action: {
-          foo: {},
+        hooks: {
+          actions: {
+            foo: {},
+          },
         },
       };
       const platformCfg = {

docs/src/content/docs/reference/config.md

@@ -156,7 +156,6 @@ You would then change your npm script or CLI command to run that file with Node:
 | `transform`      | `Record<string, Transform>`      | Custom [transforms](/reference/hooks/transforms) you can include inline rather than using `.registerTransform`. The keys in this object will be the transform's name, the value should be an object with `type`                                                                                                                            |
 | `transformGroup` | `Record<string, TransformGroup>` | Custom [transformGroups](/reference/hooks/transform_groups) you can include inline rather than using `.registerTransformGroup`. The keys in this object will be the transformGroup's name, the value should be an array with `transform`s                                                                                                  |
 | `format`         | `Record<string, Format>`         | Custom [formats](/reference/hooks/formats) you can include inline in the configuration rather than using `.registerFormat`. The keys in this object will be for format's name and value should be the formatter function.                                                                                                                  |
-| `action`         | `Record<string, Action>`         | Custom inline [actions](/reference/hooks/actions). The keys in this object will be the action's name and the value should be an object containing `do` and `undo` methods.                                                                                                                                                                 |
 | `usesDtcg`       | `boolean`                        | Whether the tokens are using [DTCG Format](https://tr.designtokens.org/format/) or not. Usually you won't need to configure this, as style-dictionary will auto-detect this format.                                                                                                                                                        |
 
 ### Log

docs/src/content/docs/version-4/migration.md

@@ -240,6 +240,39 @@ StyleDictionary.registerTransform({
 });
 ```
 
+### Actions
+
+Actions, when registered, are put inside the `hooks.actions` property now, as opposed to `action`.
+Note the change from singular to plural form here.
+
+```js title="config.js" del={2-7} ins={8-15} /action(s): {/
+export default {
+  action: {
+    'copy-assets': {
+      do: () => {}
+      undo: () => {}
+    }
+  },
+  hooks: {
+    actions: {
+      'copy-assets': {
+        do: () => {}
+        undo: () => {}
+      }
+    },
+  },
+  platforms: {
+    css: {
+      actions: ['copy-assets'],
+      files: [{
+        format: 'css/variables',
+        destination: '_variables.css',
+      }],
+    },
+  },
+};
+```
+
 ## CTI reliance
 
 [CTI or Category / Type / Item](/info/tokens/#category--type--item) used to be the default way of structuring design tokens in Style Dictionary.

lib/Register.js

@@ -1,7 +1,7 @@
 import transform from './common/transforms.js';
 import transformGroup from './common/transformGroups.js';
 import format from './common/formats.js';
-import action from './common/actions.js';
+import actionBuiltins from './common/actions.js';
 import filterBuiltins from './common/filters.js';
 import { deepmerge } from './utils/deepmerge.js';
 
@@ -17,6 +17,22 @@ import { deepmerge } from './utils/deepmerge.js';
  * @typedef {import('../types/Config.d.ts').Hooks} Hooks
  */
 
+/**
+ * @param {typeof Register | Register} target
+ */
+function initHooks(target) {
+  target.hooks = {
+    preprocessors: {},
+    fileHeaders: {},
+    filters: {
+      ...filterBuiltins,
+    },
+    actions: {
+      ...actionBuiltins,
+    },
+  };
+}
+
 export class Register {
   /**
    * Below is a ton of boilerplate. Explanation:
@@ -33,12 +49,14 @@ export class Register {
     filters: {
       ...filterBuiltins,
     },
+    actions: {
+      ...actionBuiltins,
+    },
   };
 
   static transform = transform;
   static transformGroup = transformGroup;
   static format = format;
-  static action = action;
   /** @type {Parser[]} */
   static parsers = []; // we need to initialise the array, since we don't have built-in parsers
 
@@ -225,26 +243,19 @@ export class Register {
     if (typeof name !== 'string') throw new Error('name must be a string');
     if (typeof _do !== 'function') throw new Error('do must be a function');
     // make sure to trigger the setter
-    target.action = {
-      ...target.action,
-      [name]: {
-        do: _do,
-        undo,
+    target.hooks = {
+      ...target.hooks,
+      actions: {
+        ...target.hooks.actions,
+        [name]: {
+          do: _do,
+          undo,
+        },
       },
     };
     return target;
   }
 
-  get action() {
-    const ctor = /** @type {typeof Register} */ (this.constructor);
-    return { ...ctor.action, ...this._action };
-  }
-
-  /** @param {Record<string, Omit<Action,'name'>>} v */
-  set action(v) {
-    this._action = v;
-  }
-
   /**
    * @param {Filter} cfg
    */
@@ -404,13 +415,8 @@ export class Register {
     this.transform = {};
     this.transformGroup = {};
     this.format = {};
-    this.action = {};
     this.parsers = []; // we need to initialise the array, since we don't have built-in parsers
-
-    this.hooks = {
-      preprocessors: {},
-      fileHeaders: {},
-      filters: {},
-    };
+    initHooks(this);
   }
 }
+initHooks(Register);

lib/StyleDictionary.js

@@ -82,7 +82,6 @@ export default class StyleDictionary extends Register {
         transform: this.transform,
         transformGroup: this.transformGroup,
         format: this.format,
-        action: this.action,
         parsers: this.parsers,
         hooks: this.hooks,
       },

lib/transform/config.js

@@ -21,6 +21,7 @@ import chalk from 'chalk';
  * @typedef {import('../StyleDictionary.js').default} StyleDictionary
  * @typedef {import('../../types/Transform.d.ts').Transform} Transform
  * @typedef {import('../../types/File.d.ts').File} File
+ * @typedef {import('../../types/Action.d.ts').Action} Action
  * @typedef {import('../../types/Config.d.ts').PlatformConfig} PlatformConfig
  */
 
@@ -192,7 +193,7 @@ None of ${transform_warnings} match the name of a registered transform.
   const actions = /** @type {string[]|undefined} */ (to_ret.actions) || [];
   to_ret.actions = actions.map(
     /** @param {string} action */ function (action) {
-      if (typeof dictionary.action[action].undo !== 'function') {
+      if (typeof dictionary.hooks.actions?.[action].undo !== 'function') {
         const message = `${action} action does not have a clean function!`;
         if (to_ret.log?.warnings === 'error') {
           throw new Error(message);
@@ -201,7 +202,8 @@ None of ${transform_warnings} match the name of a registered transform.
           console.log(chalk.rgb(255, 140, 0).bold(message));
         }
       }
-      return dictionary.action[action];
+      // TODO: we assume it exists, but perhaps we should check and throw error if action cannot be found
+      return /** @type {Omit<Action, "name">} */ (dictionary.hooks.actions?.[action]);
     },
   );
 

types/Config.d.ts

@@ -24,6 +24,7 @@ export interface Hooks {
   preprocessors?: Record<string, Preprocessor['preprocessor']>;
   fileHeaders?: Record<string, FileHeader>;
   filters?: Record<string, Filter['filter']>;
+  actions?: Record<string, Omit<Action, 'name'>>;
 }
 
 export interface LocalOptions {
@@ -106,6 +107,5 @@ export interface Config {
   transform?: Record<string, Transform>;
   transformGroup?: Record<string, string[]>;
   format?: Record<string, Formatter>;
-  action?: Record<string, Action>;
   usesDtcg?: boolean;
 }