Merge pull request #192 from rlaffers/migration-internal-external-transitions

Update the migration guide about internal/external transitions

Author: davidkpiano

versioned_docs/version-5/migration.mdx

@@ -649,6 +649,192 @@ const machine = createMachine({
 </TabItem>
 </Tabs>
 
+### Transitions are internal by default, not external
+
+:::breakingchange
+
+Breaking change
+
+:::
+
+All transitions are implicitly internal. This change is relevant for transitions defined on compound state nodes with `entry` or `exit` actions, invoked actors, or delayed transitions (`after`). If you relied on implicit re-entering of a compound state node, use `reenter: true`:
+
+<Tabs>
+<TabItem value="v5" label="XState v5 beta">
+
+```ts
+// ✅
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      entry: 'someAction',
+      on: {
+        someEvent: {
+          target: 'compoundState.childState',
+          // Reenters the `compoundState` state,
+          // just like an external transition
+          reenter: true,
+        },
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+
+<TabItem value="v4" label="XState v4">
+
+```ts
+// ❌ DEPRECATED
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      entry: 'someAction',
+      on: {
+        someEvent: {
+          // implicitly external
+          target: 'compoundState.childState', // non-relative target
+        },
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+</Tabs>
+
+<Tabs>
+<TabItem value="v5" label="XState v5 beta">
+
+```ts
+// ✅
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      after: {
+        1000: {
+          target: 'compoundState.childState',
+          reenter: true, // make it external explicitly!
+        }
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+
+<TabItem value="v4" label="XState v4">
+
+```ts
+// ❌ DEPRECATED
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      after: {
+        1000: {
+          // implicitly external
+          target: 'compoundState.childState', // non-relative target
+        }
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+</Tabs>
+
+### Child state nodes are always re-entered
+
+:::breakingchange
+
+Breaking change
+
+:::
+
+Child state nodes are always re-entered when they are targeted by transitions (both external and **internal**) defined on compound state nodes. This change is relevant only if a child state node has `entry` or `exit` actions, invoked actors, or delayed transitions (`after`). Add a `stateIn` guard to prevent undesirable re-entry of the child state:
+
+<Tabs>
+<TabItem value="v5" label="XState v5 beta">
+
+```ts
+// ✅
+
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      on: {
+        someEvent: {
+          guard: not(stateIn({ compoundState: 'childState' }),
+          target: '.childState',
+        },
+      },
+      initial: 'childState',
+      states: {
+        childState: {
+          entry: 'someAction',
+        },
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+
+<TabItem value="v4" label="XState v4">
+
+```ts
+// ❌ DEPRECATED
+
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      on: {
+        someEvent: {
+          target: '.childState', // implicitly internal, childState not re-entered
+        },
+      },
+      initial: 'childState',
+      states: {
+        childState: {
+          entry: 'someAction',
+        },
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+
+</Tabs>
+
 ### Use `stateIn()` to validate state transitions, not `in`
 
 :::breakingchange