Annotate/refactor store events example (#2400)

This example refactors the store events example to use the store.listen
method and adds annotations to explain the code.

### Change Type

- [ ] `patch` — Bug fix
- [ ] `minor` — New feature
- [ ] `major` — Breaking change
- [ ] `dependencies` — Changes to package dependencies[^1]
- [x] `documentation` — Changes to the documentation only[^2]
- [ ] `tests` — Changes to any test code only[^2]
- [ ] `internal` — Any other changes that don't affect the published
package[^2]
- [ ] I don't know

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

### Test Plan

1. Add a step-by-step description of how to test your PR here.
2.

- [ ] Unit Tests
- [ ] End to end tests

### Release Notes

- Update store events example to use store.listen method
- Annotate with explanations of the code

apps/examples/src/examples/store-events/StoreEventsExample.tsx

@@ -2,6 +2,8 @@ import { Editor, TLEventMapHandler, Tldraw } from '@tldraw/tldraw'
 import '@tldraw/tldraw/tldraw.css'
 import { useCallback, useEffect, useState } from 'react'
 
+// There's a guide at the bottom of this file!
+
 export default function StoreEventsExample() {
 	const [editor, setEditor] = useState<Editor>()
 
@@ -18,40 +20,39 @@ export default function StoreEventsExample() {
 			setStoreEvents((events) => [eventName, ...events])
 		}
 
-		// This is the fire hose, it will be called at the end of every transaction
+		//[1]
 		const handleChangeEvent: TLEventMapHandler<'change'> = (change) => {
-			if (change.source === 'user') {
+			// Added
-				// Added
+			for (const record of Object.values(change.changes.added)) {
-				for (const record of Object.values(change.changes.added)) {
+				if (record.typeName === 'shape') {
-					if (record.typeName === 'shape') {
+					logChangeEvent(`created shape (${record.type})`)
-						logChangeEvent(`created shape (${record.type})`)
-					}
 				}
+			}
 
-				// Updated
+			// Updated
-				for (const [from, to] of Object.values(change.changes.updated)) {
+			for (const [from, to] of Object.values(change.changes.updated)) {
-					if (
+				if (
-						from.typeName === 'instance' &&
+					from.typeName === 'instance' &&
-						to.typeName === 'instance' &&
+					to.typeName === 'instance' &&
-						from.currentPageId !== to.currentPageId
+					from.currentPageId !== to.currentPageId
-					) {
+				) {
-						logChangeEvent(`changed page (${from.currentPageId}, ${to.currentPageId})`)
+					logChangeEvent(`changed page (${from.currentPageId}, ${to.currentPageId})`)
-					}
 				}
+			}
 
-				// Removed
+			// Removed
-				for (const record of Object.values(change.changes.removed)) {
+			for (const record of Object.values(change.changes.removed)) {
-					if (record.typeName === 'shape') {
+				if (record.typeName === 'shape') {
-						logChangeEvent(`deleted shape (${record.type})`)
+					logChangeEvent(`deleted shape (${record.type})`)
-					}
 				}
 			}
 		}
 
-		editor.on('change', handleChangeEvent)
+		// [2]
+		const cleanupFunction = editor.store.listen(handleChangeEvent, { source: 'user', scope: 'all' })
 
 		return () => {
-			editor.off('change', handleChangeEvent)
+			cleanupFunction()
 		}
 	}, [editor])
 
@@ -82,3 +83,20 @@ export default function StoreEventsExample() {
 		</div>
 	)
 }
+
+/* 
+This example shows how to listen to store events. This includes things creating/deleting shapes,
+or moving between pages, but not things such as pointer and keyboard events. Those are canvas events.
+To listen to changes to the canvas, check out the canvas events example.
+
+[1]
+This is the fire hose, it will be called at the end of every transaction. We're checking to see what 
+kind of changes were made and logging a more readable message to the to our panel.
+
+[2]
+This is the function that subscribes to changes to the store. You pass in the callback function that 
+you want to execute along with a handy filter object. In this case, we're only listening to changes
+that were made by the user. It also returns a cleanup function that you can shove into the return of 
+a useeffect hook.
+
+*/