Merge pull request #257 from statelyai/davidkpiano/update-params

Update action and guard params

Author: davidkpiano

docs/actions.mdx

@@ -27,8 +27,8 @@ const feedbackMachine = createMachine({
   }
 }, {
   actions: {
-    track: ({ action }) => {
-      track(action.params);
+    track: (_, params) => {
+      track(params);
       // tracks { response: 'good' }
     },
     showConfetti: () => {
@@ -249,7 +249,7 @@ const feedbackMachine = createMachine(
   {
     // highlight-start
     actions: {
-      track: ({ context, event }) => {
+      track: ({ context, event }, params) => {
         // Action implementation
         // ...
       },
@@ -266,7 +266,7 @@ const feedbackActor = createActor(
   // highlight-start
   feedbackMachine.provide({
     actions: {
-      track: ({ context, event }) => {
+      track: ({ context, event }, params) => {
         // Overridden action implementation
         // ...
       },

docs/cheatsheet.mdx

@@ -266,8 +266,8 @@ const machine = createMachine({
 const actor = createActor(
   machine.provide({
     actions: {
-      notify: ({ action }) => {
-        console.log(action.params.message ?? 'Default message');
+      notify: (_, params) => {
+        console.log(params.message ?? 'Default message');
       },
       activate: () => {
         console.log('Activating');
@@ -337,8 +337,8 @@ const actor = createActor(
     // highlight-start
     guards: {
       canBeToggled: ({ context }) => context.canActivate,
-      isAfterTime: ({ guard }) => {
-        const { time } = guard.params;
+      isAfterTime: (_, params) => {
+        const { time } = params;
         const [hour, minute] = time.split(':');
         const now = new Date();
         return now.getHours() > hour && now.getMinutes() > minute;

docs/guards.mdx

@@ -143,10 +143,10 @@ const feedbackMachine = createMachine(
   {
     // highlight-start
     guards: {
-      isValid: ({ context, guard }) => {
+      isValid: ({ context }, params) => {
         return (
           context.feedback.length > 0 &&
-          context.feedback.length <= guard.maxLength
+          context.feedback.length <= params.maxLength
         );
       },
     },
@@ -162,10 +162,10 @@ const feedbackActor = createActor(
   // highlight-start
   feedbackMachine.provide({
     guards: {
-      isValid: ({ context, guard }) => {
+      isValid: ({ context }, params) => {
         return (
           context.feedback.length > 0 &&
-          context.feedback.length <= guard.maxLength &&
+          context.feedback.length <= params.maxLength &&
           isNotSpam(context.feedback)
         );
       },

docs/migration.mdx

@@ -456,15 +456,15 @@ const machine = createMachine({
 </TabItem>
 </Tabs>
 
-### Use `params` to pass custom event data
+### Use `params` to pass params to actions & guards
 
 :::breakingchange
 
 Breaking change
 
 :::
 
-Properties other than `type` on action objects and guard objects should be nested under a `params` property; `{ type: 'someType', message: 'hello' }` becomes `{ type: 'someType', params: { message: 'hello' }}`:
+Properties other than `type` on action objects and guard objects should be nested under a `params` property; `{ type: 'someType', message: 'hello' }` becomes `{ type: 'someType', params: { message: 'hello' }}`. These `params` are then passed to the 2nd argument of the action or guard implementation:
 
 <Tabs>
 <TabItem value="v5" label="XState v5 beta">
@@ -478,6 +478,22 @@ const machine = createMachine({
       message: 'Hello world',
     },
   },
+  on: {
+    someEvent: {
+      guard: { type: 'isGreaterThan', params: { value: 42 } },
+    },
+  },
+}).provide({
+  actions: {
+    greet: ({ context, event }, params) => {
+      console.log(params.message); // 'Hello world'
+    },
+  },
+  guards: {
+    isGreaterThan: ({ context, event }, params) => {
+      return event.value > params.value;
+    },
+  },
 });
 ```
 
@@ -487,12 +503,31 @@ const machine = createMachine({
 
 ```ts
 // ❌ DEPRECATED
-const machine = createMachine({
-  entry: {
-    type: 'greet',
-    message: 'Hello world',
+const machine = createMachine(
+  {
+    entry: {
+      type: 'greet',
+      message: 'Hello world',
+    },
+    on: {
+      someEvent: {
+        cond: { type: 'isGreaterThan', value: 42 },
+      },
+    },
   },
-});
+  {
+    actions: {
+      greet: (context, event, { action }) => {
+        console.log(action.message); // 'Hello world'
+      },
+    },
+    guards: {
+      isGreaterThan: (context, event, { guard }) => {
+        return event.value > guard.value;
+      },
+    },
+  },
+);
 ```
 
 </TabItem>