From a6d2f6f8e56a67b142b64f5d55eec4b7dc96d2c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Hamburger=20Gr=C3=B8ngaard?=
 <christian.groengaard@sanity.io>
Date: Fri, 3 Jan 2025 09:10:35 +0100
Subject: [PATCH] docs: document `raise` action

---
 .../content/docs/reference/behavior-api.mdx   | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/apps/docs/src/content/docs/reference/behavior-api.mdx b/apps/docs/src/content/docs/reference/behavior-api.mdx
index 05ff1b607..3cdd1278c 100644
--- a/apps/docs/src/content/docs/reference/behavior-api.mdx
+++ b/apps/docs/src/content/docs/reference/behavior-api.mdx
@@ -89,9 +89,56 @@ Additional actions
 - delete.block
 - delete.text
 - effect
+- raise
 - select.previous block
 - select.next block
 - style.add
 - style.remove
 - text block.set
 - text block.unset
+
+## Raising Synthetic Events
+
+Synthetic events can be raised using the `raise` action:
+
+```tsx
+const raisedUppercaseA = defineBehavior({
+  on: 'insert.text',
+  guard: ({event, context}) => event.text === 'a',
+  actions: [
+    ({event, context}) => [
+      {type: 'raise', event: {type: 'insert.text', text: 'A'}},
+    ],
+  ],
+})
+```
+
+The `raise` action also has a handy shorthand function:
+
+```tsx
+const raisedUppercaseA = defineBehavior({
+  on: 'insert.text',
+  guard: ({event, context}) => event.text === 'a',
+  actions: [({event, context}) => [raise({type: 'insert.text', text: 'A'})]],
+})
+```
+
+When raising and event rather than performing the action directly, the event is sent back into the editor, allowing other behaviors to respond:
+
+```tsx
+const unoReverseUppercaseA = defineBehavior({
+  on: 'insert.text',
+  guard: ({event, context}) => event.text === 'A',
+  actions: [({event, context}) => [{type: 'insert.text', text: 'a'}]],
+})
+```
+
+However, be careful as this can can lead to infinite loops:
+
+```tsx
+const raisedLowercaseA = defineBehavior({
+  on: 'insert.text',
+  guard: ({event, context}) => event.text === 'A',
+  actions: [({event, context}) => [raise({type: 'insert.text', text: 'a'})]],
+})
+```