You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update v4 Community page with content from v5
* Add new team page
* Update some Community features
* Update featues on the Pro plan
* Remove 7 day trial bullet point
* Fix broken link
* Start to add teams content to team page
* Add team page for v5 and make the content the same as v4
* Specify "view-only"
* Add features to Pro pages
* More text changes applied to both Pro pages
* Revise text about free trial on the Community page
* Revise the high level prompt to upgrade to a Team plan
* Revise the high level prompt to upgrade to a Pro plan
* Add team feature and re-order
* Add link to teams feature page and fix pro page link
* Add links to Team features
* Clarify some pro vs team features
* Update the Teams page with the new Team plan in mind
* Move "Live collaboration" from Pro to Team plan pages
* Add the word Plan to the title of each plan to distinguish "Team Plan" from Team (feature)
* Make the trial admonition more generic on the Enterprise Plan page
* Revise text to say "plan" instead of "account"
* Fix message
* Specify Enterprise when mentioning the free trial on the Enterprise Plan pages
* Flesh out features for the Enterprise pages
* Improve the opening paragraphs of the paid plan pages
* Indicate that Pro and Team features are all included in the Enterprise Plan
* Make the trial admonition more general for all plans on the Sign Up page
* Make the trial messages the same across pages for consistency
* Add Team plan to Accounts page, Sidebar, and add Team badge
* Remove Team badge from Docs
* Add mention of Team plan in the Upgrade page
* Remove mention of modifying # of seats in a plan
* Move Team Shared Projects section to the Team page
* Move more shared team projects content to the Team pages
* Add a line about selecting Project Visibility when creating a shared project
* Revise upgrade text
* Replace "via" with "with"
* Update docs/teams.mdx
Co-authored-by: Laura Kalbag <[email protected]>
* Fix typo and make v4/5 pages the same
* Fix links
* Fix broken links
* Remove Stately Studio howtos from concept + XState docs
Also remove now-redundant SkipDownLink component
* Remove redundant component imports
* Remove more Studio howtos from Guards page
* First draft of Studio-specific states and transitions page
* Add initial draft of editor tags page
* Add tags to sidebar under Design Mode
* Add simpler title h1 for states and transitions page
* Improve editor tags docs
* Remove Studio howtos
* Initial drafts of actions and actors and context pages
* Provide alternatives to right-click
* Add more info on deleting
* Fix URL
* Small tweaks
* Update todo link
* Link to relevant studio content from XState docs
Closes STA-5673
* Fix broken URL
* Add embedded machines to demonstrate Studio concepts
Closes STA-5678
* Fix embed URL
---------
Co-authored-by: Kevin Maes <[email protected]>
Copy file name to clipboardExpand all lines: docs/actions.mdx
+6-125Lines changed: 6 additions & 125 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,12 @@ title: 'Actions'
4
4
5
5
Actions are fire-and-forget effects. When a state machine transitions, it may execute actions. Actions occur in response to events, and are typically defined on transitions in the `actions: ...` property. Anywhere you can use an action, you can also declare it as an array to express multiple actions.
6
6
7
+
:::studio
8
+
9
+
You can visualize your state machines and easily add actions in our drag-and-drop Stately editor. [Read more about actions in Stately’s editor](editor-actions-and-actors.mdx).
10
+
11
+
:::
12
+
7
13
Actions can also be on a states’ `entry` or `exit`, also as a single action or an array.
8
14
9
15
```ts
@@ -44,131 +50,6 @@ Examples of actions:
44
50
- Sending a message to another [actor](actors.mdx)
45
51
-_Coming soon: more examples_
46
52
47
-
<SkipDownLink
48
-
text="Jump to learning more about entry and exit actions in XState"
49
-
link="#entry-and-exit-actions"
50
-
/>
51
-
52
-
## Using actions in Stately Studio
53
-
54
-
In our video player machine, we have entry and exit actions on the Playing state. We use the entry action of playVideo to fire an effect playing the video on entry to the Playing state. We use the exit action of pauseVideo to fire an effect pausing the video when the Playing state is exited.
First, select the event where you want an action to be fired.
64
-
65
-
### On the canvas
66
-
67
-
1. Use the <Plussize={18} /> plus icon button to open the edit menu.
68
-
2. Choose <Zapsize={18} /> **Action** from the menu to add an action block.
69
-
3. Write your action’s name in the action’s text input.
70
-
71
-
### Using the event details panel
72
-
73
-
1. Open the event <Infosize={18} /> **Details** panel from the right tool menu.
74
-
2. Use the **+ Transition action** button to add an action block.
75
-
3. Write your action’s name in the action’s text input.
76
-
77
-
## Delete a transition action
78
-
79
-
First, select the transition action block you want to delete.
80
-
81
-
### Using backspace
82
-
83
-
Use the <kbd>Backspace</kbd> key to delete the transition action.
84
-
85
-
### Using the event details panel
86
-
87
-
1. Open the event <Infosize={18} /> **Details** panel from the right tool menu.
88
-
2. Hover, focus, or select the transition action block to reveal the <Trashsize={18} /> trash icon button.
89
-
3. Use the <Trashsize={18} /> trash icon button to delete the action.
90
-
91
-
## Add an entry action or exit action to a state
92
-
93
-
First, select the state you want to have an entry or exit action.
94
-
95
-
### On the canvas
96
-
97
-
1. Select the state where you want to add an action.
98
-
2. Use the <Plussize={18} /> plus icon button to open the edit menu.
99
-
3. Choose <Zapsize={18} /> **Entry action** or <Zapsize={18} /> **Exit action** from the menu to add an action block to the event.
100
-
4. Write your action’s name in the action’s text input.
101
-
102
-
### Using the event details panel
103
-
104
-
1. Open the state <Infosize={18} /> **Details** panel from the right tool menu.
105
-
2. Use the **+ Effect** button to open the effects menu, and choose **Add entry action** or **Add exit action**.
106
-
3. Write your action’s name in the action’s text input.
107
-
108
-
## Delete an entry action or exit action from a state
109
-
110
-
First, select the action block you want to delete.
111
-
112
-
### Using backspace
113
-
114
-
Use the <kbd>Backspace</kbd> key to delete the action.
115
-
116
-
### Using the event details panel
117
-
118
-
1. Open the event <Infosize={18} /> **Details** panel from the right tool menu.
119
-
2. Hover, focus, or select the action block to reveal the <Trashsize={18} /> trash icon button.
120
-
3. Use the <Trashsize={18} /> trash icon button to delete the action.
121
-
122
-
## Add a built-in action
123
-
124
-
You can add built-in XState actions which will be formatted in your [exported code](export-as-code.mdx). The options are:
125
-
126
-
-[assign](#assign-action): assigns data to the state context.
127
-
-[raise](#raise-action): _raises_ an event that is received by the same machine.
128
-
-[log](#log-action): an easy way to log messages to the console.
129
-
-[sendTo](#send-to-action): sends an event to a specific actor.
130
-
-[stop](#stop-action): stops a child actor.
131
-
132
-
To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
133
-
134
-
### On the canvas
135
-
136
-
1. Hover, focus, or select the action block to reveal the <Editsize={18} /> edit icon button.
137
-
2. Use the <Editsize={18} /> edit icon button to open the **Action** panel.
138
-
3. Choose your desired action from the dropdown menu at the top of the **Action** panel.
139
-
4. Fill out the required corresponding action input fields.
140
-
141
-
### Using the details panel
142
-
143
-
1. Open the state, or event <Infosize={18} /> **Details** panel from the right tool menu.
144
-
1. Hover, focus, or select the action block to reveal the <Editsize={18} /> edit icon button.
145
-
1. Use the <Editsize={18} /> edit icon button to open the **Action** panel.
146
-
1. Choose your desired action from the dropdown menu at the top of the **Action** panel.
147
-
1. Fill out the required corresponding action input fields.
148
-
149
-
## Add a custom action
150
-
151
-
You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](#action-objects) in your [exported code](export-as-code.mdx).
152
-
153
-
First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
154
-
155
-
### On the canvas
156
-
157
-
1. Hover, focus, or select the action block to reveal the <Editsize={18} /> edit icon button.
158
-
2. Use the <Editsize={18} /> edit icon button to open the **Action** panel.
159
-
3. Custom action is selected by default. Add your custom action type in the **Action type** text input.
160
-
4. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
161
-
162
-
[Read about action objects below for more on action types and and parameters](#action-objects).
163
-
164
-
### Using the details panel
165
-
166
-
1. Open the state, or event <Infosize={18} /> **Details** panel from the right tool menu.
167
-
1. Hover, focus, or select the action block to reveal the <Editsize={18} /> edit icon button.
168
-
1. Use the <Editsize={18} /> edit icon button to open the **Action** panel.
169
-
1. Custom action is selected by default. Add your custom action type in the **Action type** text input.
170
-
1. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
171
-
172
53
## Entry and exit actions
173
54
174
55
Entry actions are actions that occur on any transition that enters a state node.
Copy file name to clipboardExpand all lines: docs/actors.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,24 +2,24 @@
2
2
title: 'Actors'
3
3
---
4
4
5
-
importThemedImagefrom'@theme/ThemedImage';
6
-
7
5
When you run a state machine, it becomes an actor: a running process that can receive events, send events and change its behavior based on the events it receives, which can cause effects outside of the actor.
8
6
9
7
In state machines, actors can be **invoked** or **spawned**. These are essentially the same, with the only difference being how the actor’s lifecycle is controlled.
10
8
11
9
- An **invoked actor** is started when its parent machine enters the [state](states.mdx) it is invoked in, and stopped when that state is exited.
12
10
- A **spawned actor** is started in a [transition](transitions.mdx) and stopped either with a [`stop(...)` action](actions.mdx#stop-action) or when its parent machine is stopped.
13
11
14
-
:::tip
12
+
:::studio
15
13
16
-
Watch our [“What are invoked actors?” video on YouTube](https://www.youtube.com/watch?v=TRMS8NYKWnA&list=PLvWgkXBB3dd4I_l-djWVU2UGPyBgKfnTQ&index=9) (1m57s).
14
+
You can visualize your state machines and easily invoke actors in our drag-and-drop Stately editor. [Read more about actors in Stately’s editor](editor-actions-and-actors.mdx).
17
15
18
16
:::
19
17
20
-
## Using actors in Stately Studio
18
+
:::tip
21
19
22
-
[Read about using invoked actors in Stately Studio](invoke.mdx#using-invoked-actors-in-stately-studio).
20
+
Watch our [“What are invoked actors?” video on YouTube](https://www.youtube.com/watch?v=TRMS8NYKWnA&list=PLvWgkXBB3dd4I_l-djWVU2UGPyBgKfnTQ&index=9) (1m57s).
In XState, `context` is how you store data in a state machine [actor](actors.mdx).
8
6
9
7
The `context` property is available in all states and used to store data relevant to an actor. The `context` object is immutable, so you cannot directly modify it. Instead, for state machine logic, you can use the `assign(...)` action to update `context`.
@@ -30,19 +28,6 @@ feedbackActor.start();
30
28
// logs 'Some feedback'
31
29
```
32
30
33
-
<SkipDownLink
34
-
text="Jump to learning more about context in XState"
35
-
link="#initial-context"
36
-
/>
37
-
38
-
## Using context in Stately Studio
39
-
40
-
- Coming soon… setting initial values
41
-
- Coming soon… updating context with assign
42
-
- Coming soon… JS/TS export
43
-
44
-
---
45
-
46
31
## Initial context
47
32
48
33
Set the initial context of a machine in the `context` property of the machine config:
Delayed transitions are defined on the `after` property in milliseconds. They are often referred to as “after” transitions.
8
8
9
+
:::studio
10
+
11
+
You can easily visualize and simulate delayed transitions in Stately’s editor. [Read more about delayed transitions in Stately’s editor](/docs/editor-states-and-transitions/#delayed-after-transitions).
12
+
13
+
:::
14
+
9
15
```ts
10
16
import { createMachine } from'xstate';
11
17
@@ -40,11 +46,6 @@ Watch our [“Delayed (after) transitions” video on YouTube](https://www.youtu
40
46
41
47
:::
42
48
43
-
<SkipDownLink
44
-
text="Jump to learning more about delays in XState"
@@ -54,35 +55,6 @@ Watch our [“Delayed (after) transitions” video on YouTube](https://www.youtu
54
55
55
56
In a video player, want the video to be *Closed* out of fullscreen mode a few seconds after the video has *Stopped*, instead of closing the fullscreen mode suddenly as soon as the video is stopped. The eventless transition above transitions from the *Stopped* state to the *Closed* state after 5 seconds.
56
57
57
-
## Using delayed transitions in Stately Studio
58
-
59
-
In Stately Studio, delayed transitions are labeled “after.”
60
-
61
-
### Make an event into a delayed transition
62
-
63
-
Delayed transitions have a default time interval of 500ms (0.5 seconds).
64
-
65
-
#### On the canvas
66
-
67
-
1. Select the event you want to replace with a delayed transition.
68
-
1. Right-click the event to open the edit menu.
69
-
1. From the **Event type** options, choose **After** to turn the event into a delayed transition.
70
-
71
-
#### Using the transition Details panel
72
-
73
-
1. Open the transition <Infosize={18} /> **Details** panel from the right tool menu.
74
-
2. From the **Event type** dropdown menu, choose **After** to turn the event into a delayed transition.
75
-
76
-
#### Specify delay time
77
-
78
-
Your delay time interval will be displayed in a human-readable format on hover. For example, 15000ms will be displayed as 15 seconds.
79
-
80
-
1. Select the delayed transition.
81
-
2. Open the transition <Infosize={18} /> **Details** panel from the right tool menu.
82
-
3. Use the **Delay** text input to specify the interval in milliseconds.
83
-
84
-
---
85
-
86
58
## Delays
87
59
88
60
You can define delays in a few ways: [inlined](#inlined-delays), [referenced](#referenced-delays), and [as an expression](#delay-expressions).
description: 'Learn how to use exit actions, entry actions, and transition actions, and invoke actors in Stately’s editor.'
4
+
---
5
+
6
+
# Actions and actors
7
+
8
+
While the statechart is running, it can execute other effects called actions. You can fire an action upon entry or exit of a state. Actions are “fire-and-forget effects”; once the machine has fired the action, it moves on and forgets the action. You can also fire actions on transitions. [Read more about actions](actions.mdx).
9
+
10
+
State machines can invoke actors as longer-running processes that can receive events, send events, and change their behavior based on the events they receive. You can invoke actors on entry to a state and stop on exit. [Read more about actors](actors.mdx).
11
+
12
+
<EmbedMachineembedURL="https://stately.ai/registry/editor/embed/c447d996-cef1-421d-a422-8be695668764?code=834448b4-3b8b-4de9-8b2e-353fd2b342de&mode=design&machineId=000b2694-2267-413c-8477-988cc750d581"title="Demo of actions and actors"/>
13
+
14
+
## Add actions
15
+
16
+
- Select a state and use <Plussize={18} /> **Entry action** or **Exit action**.
17
+
- Select a transition and use <Plussize={18} /> **Action**.
18
+
- Select a state or transition, open the <Infosize={18} /> **Details** panel from the right tool menu, and use the <Plussize={18} /> **Effect** or <Plussize={18} /> **Action** button and choose **Add entry action**, **Add exit action**, or **Add action**.
19
+
20
+
Use the <Editsize={18} /> edit icon button to open the **Action** panel and add custom action parameters. Actions are created as custom actions by default, but you can also use [XState built-in actions](#xstate-built-in-actions).
21
+
22
+
To remove an action, use the <kbd>Backspace</kbd> key, *right-click* and choose **Delete**, or use the <Trashsize={18} /> delete icon button in the **Details** panel.
23
+
24
+
### XState built-in actions
25
+
26
+
You can choose from the following built-in XState actions, which will be formatted in your [exported code](export-as-code.mdx). The options are:
27
+
28
+
-[assign](/docs/actions/#assign-action): assigns data to the state context.
29
+
-[raise](/docs/actions/#raise-action): raises an event that is received by the same machine.
30
+
-[log](/docs/actions/#log-action): an easy way to log messages to the console.
31
+
-[sendTo](/docs/actions/#send-to-action): sends an event to a specific actor.
32
+
-[stop](/docs/actions/#stop-action): stops a child actor.
33
+
34
+
To add a built-in action, first [add an action](#add-actions). [Read more about actions in XState](actions.mdx).
35
+
36
+
## Add invoked actors
37
+
38
+
You can invoke multiple actors on a single state. Top-level final states cannot have invoked actors. [Read more about invoking actors](invoke.mdx).
In the video player above, the *startVideo* actor is invoked when the video player is in the *Opened* state.
46
+
47
+
### Invoke actors on a state
48
+
49
+
- Select a state and use <PlayCirclesize={18} /> **Invoke**.
50
+
- Select a state, open the state <Infosize={18} /> **Details** panel from the right tool menu, and use the <Plussize={18} /> **Effect** button and choose **Add invoked actor**.
51
+
52
+
Use the <Editsize={18} /> edit icon button to open the **Invoked actor** panel and enter the actor’s source logic and ID. The ID can be used with the [`sendTo` or `stop` actions](#xstate-built-in-actions) to stop and send events to the actor.
53
+
54
+
To remove an actor, use the <kbd>Backspace</kbd> key, *right-click* and choose **Delete**, or use the <Trashsize={18} /> delete icon button in the **Details** panel.
55
+
56
+
#### Invoke done and invoke error events
57
+
58
+
**Invoke done events** and **invoke error events** transition from a state once its invocation has been completed or returns an error. The source state must have an invoked actor to create an invoke done or invoke error event.
59
+
60
+
- Select the state with an invoked actor and create a new transition from that state. The first new transition will be created as an invoke done event.
61
+
- Subsequent new transitions will be created as invoke error events.
62
+
63
+
To change an invoke done or invoke error event back into a regular transition, Use the <MoreHorizontalsize={18} /> triple dot menu or *right-click* the transition, and from **Event type**, choose **Always**.
0 commit comments